ISVA/ISAM Most Frequently Asked Questions

 

1. IBM Support wants traces. How do I collect the requested data to help solve my problem?

2. How should I begin debugging my problem?

3. What components should I regularly be taking backups of?

4. How do I know if updating to a later ISAM version will resolve my issue?

5. Where can I find a page for a quick list of fixes by ISAM version?

6. Where can I find system requirements and other information for ISAM 8.0.X?

7. Common problems with WebSEAL servers (list)

8. I'm receiving an error "Bad Certificate" or "Unknown Certificate". How do I fix this?

9. My certificate is outdated. How did this happen? How can I address this?

10. How do I diagnose a 403 Forbidden Response in WebSEAL?

11. How do I integrate Single sign-on (SSO) and role based authorization with Microsoft applications?

12. How do I integrate ISAM with Apache's Tomcat?

13. What do I need to know about GSKit?

14. How do I change the default name-id to email (TFIM)?

15. I received an error code of HPDIA0200W on my TAM appliance. How do I resolve this?

16. My WebSEAL won't start. How can I begin to debug this?

17. How can I stay up to date with security vulnerabilities?

18. What do I need to know about ISAM 9.0.X?

19. Where can I find instructions on how to download ISAM 9.0.X?

20. What do I do if my question is not on this page? 21. What steps can I take to ensure my problem is solved in the most optimal manner?

1. IBM Support wants traces. How do I collect the requested data to help solve my problem?

If you have already opened a Problem Management Record (PMR), IBM L1/L2 Security Support may request additional tracing information to help narrow down and diagnose your question/issue. The following information is sorted by version, product, and component:

TDS 6.X/ TDS 5.2

GSKit Tracing

ISAM 8 and 9

Network Tracing

How to collect a Support File

IRA (user registry) Tracing

Debug/Snoop Tracing

OTP (One time password) Tracing

GSKit Tracing

AAC Tracing

Runtime/Authorization Server Routing Tracing

ISAM 9 ONLY: LMI Tracing

*Important*

Once the above information is collected, you can transfer the data to IBM by following these ECuRep instructions. **If you are using Salesforce, please use this link**.

For more information, please read Collecting Data for ISAM: Read first for all IBM Security Access Manager products.

Return to top of page
 

2. How should I begin debugging my problem?

If you cannot find what you need from the IBM Support Portal and you are troubleshooting an error, try checking in the error logs for your affected component. If you are unsure where your logs may be, you can try running a "find . -name "*.log" " command (Linux/Unix). If you are using the WGA, a support file contains most of the information you need to begin the debugging process. /var/log/messages and /var/pdweb/log are generally great places to start searching in your support file. You can then use the error messages displayed in these logs and check against our database (attached here for your reference).

If you have made any changes to your environment, check WHAT change was put into practice and HOW the change would affect ISAM/TFIM/TAM. You can then use this information and browse our ISAM/TAM and TFIM databases to learn more about the specific component/application in question.

If you have already tried the above and are still unsure of your next steps, open a support ticket with IBM Security Support. You can do so through the IBM Service Request Application. This allows you to open, update, monitor your service requests (formally called Problem Management Records - PMRs) on-line and to report problems on nearly all IBM supported software products. This will allow you the ability to bypass the basic set of questions allowing your problem to be directed to the proper product support team. The product support team will contact you via your preferred communication channel (email, phone, etc).

With IBM Service Request you can:

• Describe software issue and environment in problem submission form (eliminates call center contact).
• Monitor/update existing requests – view a list of all service requests associated with customer numbers for support contracts.
• Attach multiple files to service requests.
• Receive notification when your service request has been updated by IBM Support.

The IBM preferred method for opening a severity 1 issue after hours is via phone support in addition to submitting it electronically.


Return to top of page

 

3. What components should I always take backups of?

Regular backups of critical system components are a must in any environment. To preserve a well-functioning environment, always take regular backups of the following ISAM components:

ISAM Appliance - The appliance provides an internal snapshot mechanism, which creates backups of configurations, and restores them as needed. Snapshots are compressed files that are stored on the system. You can download and then open them with any zip compliant utility, such as WinRAR.

**Note: Store only a small number of snapshots on the system. Copy them regularly to a safe location and delete them on the appliance. For more information, refer to the SOP manual provided with your product.

Embedded (local) LDAP- You should always use a standard registry back-up tool, accessing over SSL the LDAPs port (636) of the appliance.

Return to top of page

 

4. How do I know if updating to a later ISAM version will resolve my issue?

Each released version fix will include a ReadMe with APARs and Defects fixed. If you are on an earlier version, consult the "APARS/Defects Fixed" stanza in the ReadMe file for later versions of ISAM (later fixes can be found in Fixes by version for IBM Security Access Manager) to see if your issue was already fixed in a future release.

If you see your issue was fixed in this stanza, IBM support recommends reviewing your product and understanding the specific implications of updating in your environment. Always take backups of all your systems before updating.

Return to top of page

 

5. Where can I find a page for a quick list of fixes by ISAM version?

The Fixes by version for IBM Security Access Manager technote is constantly updated as new versions of ISAM are released. Please bookmark this quick and easy to access page for future reference.

Return to top of page
 

6. Where can I find system requirements and other information for ISAM 8.0.X?

If you are interesting in learning more about version 8 of IBM's Security Access Manager, refer to the following documentation.

System requirements for ISAM for Web

System requirements for ISAM for Mobile

Documented PDF's:

ISAM 8.0.1.3 for Web

ISAM 8.0.1.3 for Mobile

ISAM 8.0.1.2 for Web

ISAM 8.0.1.2 for Mobile

ISAM 8.0.1.0 for Web

ISAM 8.0.1.0 for Mobile

ISAM 8.0.0.5 for Web

ISAM 8.0.0.5 for Mobile

Return to top of page

 

7. Common problems with WebSEAL servers (list)

WebSEAL version 8

WebSEAL version 9

Return to top of page

 

8. I'm receiving an error "Bad Certificate" or "Unknown Certificate". How do I fix this?

A network trace is the easiest way to diagnose this.

For appliance: Network Tracing

For software: Network Tracing

Use Wireshark or another network analyzing tool to check the certificates being sent by either WebSEAL or the backend server. These are typically in the "Client" or "Server" hello. Make sure the entire certificate chain (including the certificates in the network trace) are in the server-throwing-the-error's keystore. You can check ISAM keystores by:

1) (If appliance) Using the LMI. To do so, navigate to Manage System Settings -> Secure Settings -> SSL Certificates

2) Using a KDB file. These can be found in

• Appliance Support files. /var/pdweb/shared/
• Appliance Snapshots. /var/pdweb/shared/keytab
• Software: /var/PolicyDirector/keytab/
• Software: /var/pdweb/<instance_name>/certs/

To open a KDB, you can use the GSKit gsk7capicmd/gsk8capicmd utilities to view the contents of the KDB.

Example using gsk8capicmd:

To get a short list (labels only) of all certificates in a key database, use the following command:

gsk8capicmd_64 -cert -list -db server.kdb -stashed

The -db parameter specifies the name of the key database file.

To get detailed information about a particular certificate, use the following command:

gsk8capicmd_64 -cert -details -db server.kdb -stashed -label "My certificate"

In this command, the -db parameter specifies the name of the key database file. The -label parameter specifies the label of the certificate in the database.

(For more information, you can visit this devWorks article)

Next, confirm the certificate chain is complete. To have a complete certificate chain, there must be a Root CA, Intermediate CAs, and a top level SSL cert.

A Root CA certificate must have the "Subject" and "Issuer" as the same value. Otherwise, for every Intermediate CA and top level SSL cert, the "Issuer" must match some other certificate's "Subject" in the certificate list. Hence the term "certificate chain"

If a server's key database does not contain every certificate that is being sent over by the other server, the certificate chain is incomplete and the SSL connection will fail.

You can check the certificate chain by running the following command:

$ gsk8capicmd_64 -cert -validate -db <kdb> -stashed -label <cert label>

If there is an error, please be sure to review.

**Note**

When a certificate chain appears to be complete and there is still a "bad certificate" or "unknown certificate", list the details of each certificate, and check to make sure the certificate's

1. Extensions -> SubjectKeyIdentifier -> keyIdentifier

2. Serial number

are the same on the certificate that needs to be verified AND the certificate in the keystore.


Return to top of page

 

9. My certificate is outdated. How did this happen? How can I address this?

By default, every certificate is set to expire in a specific time frame. Depending on your product version, this default expiration may change. For example, the default expiration for an ISAM 8 certificate is 4 years.

If you have received an error message saying a certificate is expired, check to see the actual expiration date of the certificate. You can check a certificate's expiration by viewing your kdb files, either by using a dispkdb -f <kdb file> command (if using a .sth file to stash your password) or gsk8ikm, gsk8cmd, or gsk8capicmd (if you have your password configured in your configuration file).

If you can confirm the date is expired, you will need to replace the expired certificate with a new certificate, either from a CA or self-signed.

For example, to replace a root certificate on an ISAM 8 appliance:

To remove the expired certificate:
1 go to Manage System Settings - SSL Certificates
2 select and highlight the Certificate Database. For appliance root certificates it is pdsrv database.
3 press button Manage and select Edit SSL Certificate Database
4 scroll down to the expired certificate and select it.
5 press button delete to remove it.
6 then apply the undeployed changes to the appliance


To add the new certificate:
1 download the new root certificate from vendor
2 go to Manage System Settings - SSL Certificates
3 select and highlight the Certificate Database. For appliance root certificates it is pdsrv.
4 press button Manage and select Edit SSL Certificate Database
5 press button Manage and select Import
6 select the downloaded root certificate and type in the label.
7 press button Import
8 then apply the undeployed changes to the appliance

For more information on how to prevent and manage your certificate's expiration, refer to the following link: http://www.ibm.com/support/docview.wss?uid=swg21516849

If you want to learn more about Access Manager Java Runtime Application SSL certificates: http://www.ibm.com/support/docview.wss?uid=swg21452574

Return to top of page

 

10. How do I diagnose a 403 Forbidden Response in WebSEAL?

A full step-by-step guide is published here

Return to top of page

 

11. How do I integrate Single sign-on (SSO) and role based authorization with Microsoft applications?

IBM Security Access Manager's Integration Adapter is a fully supported, FREE download for all existing Security Access Manager customers using Microsoft applications. You can use this tool to integrate an SSO environment with role based authorization while using Microsoft applications.

Return to top of page

 

12. How do I integrate ISAM with Apache's Tomcat?

The following technote describes the integration and the adapter that links ISAM with Apache's Tomcat.

IBM Security Access Manager for Apache Tomcat


Return to top of page
 

13. What do I need to know about GSKit?

What is GSKit? IBM Global Security Kit (GSKit) is a library and set of command-line tools that provides SSL implementation along with base cryptographic functions (symmetric and asymmetric ciphers, random number generation, hashing, and so on) and key management.

Why is this important? Global Security Kit (GSKit) provides Secure Sockets Layer (SSL) communication between Security Access Manager systems and supported registry servers (initializes/creates SSL connections, Because all ISAM/TAM/TFIM products use SSL communications, GSKit is a key component of a secure environment.

How can I check what version of GSKit I have?

Depending on the specific operating system, the following commands can be run:

AIX: GSKit 7 GSKit 8
HP-UX: GSKit 7 GSKit 8
Linux: GSKit 7 GSKit 8
Solaris: GSKit 7 GSKit 8
Windows: GSKit 7 GSKit 8

How do I install/upgrade/uninstall GSKit?

AIX: GSKit 7 GSKit 8
HP-UX: GSKit 7 GSKit 8
Linux: GSKit 7 GSKit 8
Solaris: GSKit 7 GSKit 8
Windows: GSKit 7 GSKit 8

What is GSKit's iKeyman?

The creation and handling of X.509 certificates and keys is performed using the IBM Global Security Kit (GSKit) key management utility, gsk7ikm, also referred to as iKeyman.

General information on the iKeyman utility can be found in the IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide

Return to top of page

 

14. How do I change the default name-id to email (TFIM)?

The DefaultNameIDFormat parameter determines processing rules for the name identifier format when one of these conditions exists:

• if there is no explicit Format attribute included in the request
• if the Format attribute is set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

The value of the default name identifier format of the identity provider, if present, is obtained from the DefaultNameIDFormat parameter belonging to its corresponding partner configuration properties. Otherwise, it proceeds to retrieve the same parameter from the federation configuration properties. If the DefaultNameIDFormat parameter is not set at either partner or federation properties, it is obtained from the configuration parameter com.tivoli.am.fim.sts.saml.2.0.assertion.default.nameidformat that you set in the Default NameID Format for Assertion validation field, if present. If not, then the value defaults to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

Note: You can specify the parameter com.tivoli.am.fim.sts.saml.2.0.assertion.default.nameidformat in the Default NameID Format for Assertion validation field of the Trust Service Chain Mapping Wizard.

The parameter treats the NameID included in the assertion as a string literal and no alias service lookup is used.

The DefaultNameIDFormat parameter can be configured to use one of the following permitted values:

• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• urn:oasis:names:tc:SAML:2.0:nameid-format:transient
• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
The most common value is: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Each name identifier format works differently in processing single sign-on requests. For example, the persistent name identifier causes the server to use the alias service to look up or create an alias for the user of the federation and partner. The email address name identifier, however, causes the name identifier element to be populated with the user name of the currently authenticated user.

To use a different name identifier format other than the default value, configure the DefaultNameIDFormat parameter with a response file in the command-line interface. You can configure the parameter from the federation or partner level

• Configuring DefaultNameIDFormat (partner)
• Configuring DefaultNameIDFormat (federation level)

Note: The DefaultNameIDFormat parameter from the partner configuration takes precedence over the property from the federation configuration.

You can also modify the mapping rule so that the NameIDFormat is added to the stsuu during Federated Single Sign On.

For example add following:

<stsuuser:Principal>
<stsuuser:Attribute name="name"
type="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
<stsuuser:Value>testuser
</stsuuser:Value>
</stsuuser:Attribute>
</stsuuser:Principal>

Return to top of page
 

15. I attempted to login to WebSEAL and received an error code of HPDIA0200W. I can authenticate via pdadmin. How do I resolve this?

If you can authenticate the user in the domain with pdadmin, HPDIA0200W could indicate there is a permission problem for the WebSEAL server towards the user suffix in LDAP.

Diagnosing the problem:

Enable pd.ivc.ira tracing on the WebSEAL machine and recreate the login attempt.
Tracing can be enabled as such:

pdadmin sec_master> s t default-webseald-tam611-Webseal trace set pd.ivc.ira 9 file path=ivc.ira.txt

Then locate the ira_auth_compare() return code within the created trace ivc.ira.txt:

trace.pd.ivc.ira:8 /project/am611/build/am611/src/ivrgy/ira_ldap.c:1659: CII EXIT ira_auth_compare() with rc: 0x00000010

In case this return code is 0x10 ( 0x00000010) it means WebSEAL cannot find the userPassword attribute for the user. Since authentication via pdadmin works, it points to an ACL issue.

To Resolve:

Run the ivrgy_tool -d add-acls command, which will set all the required ACLs for the suffixes in LDAP

For more information on the ivrgy_tool

Return to top of page
 

16. My WebSEAL won't start. How can I begin to debug this?

Try starting WebSEAL in the foreground.

• AIX: webseald -config etc/webseald-instance.conf -foreground

• Windows: webseald -config etc\webseald-instance.conf -foreground

• Linux: /opt/pdweb/bin/webseald -config etc/webseald-default.conf –foreground

• Solaris:/opt/pdweb/bin/webseald -config etc/webseald-default.conf –foreground

You can then lookup the errors that are shown in our database to determine the next appropriate action

Common error codes:

If failing with error code DPWIV0201E.

If failing with error code DPWIV0164W.

If failing with error code DPWIV1051E.

Return to top of page
 

17. How can I stay up to date with security vulnerabilities?

You can stay informed of crucial ISAM/TFIM software support updates, security vulnerabilities, and other notifications with My Notifications.

• Take a proactive approach to problem prevention.
• Receive support content tailored to your needs, delivered directly to you!
• Receive immediate notifications of Security Bulletins and Flashes.
• Receive daily or weekly notifications of technical support information such as downloads, tips, technical notes, and publications.

If you have not already subscribed to an IBM product, please visit the following page for more information.

Return to top of page

 

18. What do I need to know about ISAM 9.0.X?

For a full ISAM 9 Product overview

For PDF versions of the IBM Security Access Manager 9.0 product documentation, please visit the following links:


Part 1
================
Web Reverse Proxy Configuration Topics
Advanced Access Control Configuration Topics
Federation Configuration Topics
User Registry Configuration Topics
Administration Topics
Federation Administration Topics
Advanced Access Control Administration Topics
Platform and Supporting Components Administration Topics
Reverse Proxy Stanza Reference Topics
Web API documentation


Part 2
===============================

Auditing Topics
Advanced Access Control Auditing Topics
Troubleshooting Topics
Command Reference Topics
Development Topics
Error Message Reference

Return to top of page

 

19. Where can I find instructions on how to download ISAM 9.0.X?

The following page describes how to download and assemble the IBM Security Access Manager virtual appliance from the Passport Advantage® website.

Download IBM Security Access Manager 9.0

Return to top of page
 

20. What do I do if my question is not on this page?

Additional information including documentation, tutorial videos and social channels can be found at the IBM Electronic Support Page.

You can also search our knowledge database (ISAM link, TFIM link) for in depth knowledge articles and information regarding release notes, configuration details, and much more.

Return to top of page

 

21. What steps can I take to ensure my problem is solved in the most optimal manner?

The IBM Support Portal is the one-stop-shop for finding relevant information about your products. The IBM Support Portal provides powerful features that make it fast and easy to find the exact information or tool you need.

• Select your IBM products and the task at hand for direct access to all pertinent resources.
• Browse featured support links that guide you to the most critical, useful information and tools.
• Filter the results of a simple text search with one click to pinpoint the most appropriate documents.
• Personalize the pages to include exactly the type of information you need, arranged most effectively for you.

IBM Support Portal

Return to top of page