Security authorization provider troubleshooting tips

This article describes the issues you might encounter using a Java Authorization Contract for Containers (JACC) authorization provider. Tivoli Access Manager is bundled with WebSphere Application Server as an authorization provider. However, we also can plug in our own authorization provider.

Tivoli Access Manager as a Java Authorization Contract for Containers authorization provider

This topic references one or more of the application server log files. As a recommended alternative, we can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM i systems. We can also use HPEL in conjunction with the native z/OS logging facilities. If we are using HPEL, we can access all of the log and trace information using the LogViewer command-line tool from the server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.

We might encounter the following issues when using Tivoli Access Manager as a JACC authorization provider:

• The configuration of JACC might fail.

• The server might fail to start after configuring JACC.

• The application might not deploy properly.

• The startServer command might fail after we have configured Tivoli Access Manager or a clean uninstall did not take place after unconfiguring JACC.

• HPDIA0202w An unknown user name was presented to Access Manager error might occur.

• HPDAC0778E The specified user's account is set to invaliderror might occur.

• WASX7017E: Exception received while running file InsuranceServicesSingle.jacl error might occur.

• Access denied exceptions accessing applications when using JACC

• An HPDBA0219E: An error occurred reading data from an SSL connection might occur

• (zos) A There are no ports available in the port set error might occur

External providers for Java Authorization Contract for Containers authorization provider

We might encounter the following issues when you use an external provider for JACC authorization:

• HPDJA0506E Invalid argument: Null or zero-length user name field for the ACL entry error might occur.

The configuration of JACC might fail

If we have problems configuring JACC, check the following items:

• Ensure that the parameters are correct. For example, we do not want a number after TAM_Policy_server_hostname:7135, but you do want be a number after TAM_Authorization_server_hostname:7136 (for example, TAM_Authorization_server_hostname:7136:1).

• If a message such as "server can't be contacted" is displayed, it is possible that the host names or port numbers of the Tivoli Access Manager servers are incorrect, or that the Tivoli Access Manager servers have not started.

• Ensure that the password for the sec_master user is correct.

• Check the SystemOut.log file and search for the AMAS string to see if any error messages are present.

The server might fail to start after configuring JACC

If the server does not start after JACC is configured, check the following items:

• Ensure that WebSphere Application Server and Tivoli Access Manager use the same LDAP server.

• If the message "Policy Director Authentication failed" is displayed, ensure that:

  • WebSphere Application Server LDAP server ID is the same as the "Administrator user" in the Tivoli Access Manager JACC configuration panel.

  • Verify that the Tivoli Access Manager Administrator distinguished name (DN) is correct.

  • Verify that the password of the Tivoli Access Manager administrator has not expired and is valid.

  • Ensure that the account is valid for the Tivoli Access Manager administrator.

• If a message such as socket can't be opened for xxxx (where xxxx is a number) is displayed, take the following actions:

  1. Go to the profile_root/etc/tam directory.

  2. Change xxxx to an available port number in the amwas.commomconfig.properties file, and the amwas*cellName_dmgr.properties file if the deployment manager failed to start. If the node failed to start, change xxx to an available port number in the amwas*cellName_nodeName_.properties file. If the Application Server failed to start, change xxxx in the amwas*cellname_nodeName_serverName.properties file.

The application might not deploy properly

When you click Save, the policy and role information is propagated to the Tivoli Access Manager policy. This process might take some time to finish. If the save fails, you must uninstall the application and then reinstall it.

To access an application after it is installed, you must wait 30 seconds, by default, to start the application after you save.

The startServer command might fail

The startServer command might fail after you configure Tivoli Access Manager or a clean uninstall did not take place after unconfiguring JACC.

If the cleanup for JACC unconfiguration or start server fails after JACC is configured, take the following actions:

• Remove Tivoli Access Manager properties files from WebSphere Application Server. For each application server in a WAS Network Deployment (ND) environment with N servers defined (for example, server1, server2).

  (dist)(zos) The following files must be removed.

  install_root/tivoli/tam/PdPerm.properties  install_root/tivoli/tam/PdPerm.ks
  profile_root/etc/tam/*

  (iseries) The following files must be removed.

  profile_root/etc/pd/PolicyDirector/PDPerm.properties  profile_root/etc/pd/PolicyDirector/PdPerm.ks
  profile_root/etc/tam/*

• Use a utility to clear the security configuration and return the system to the state it was in before configuring the JACC provider for Tivoli Access Manager. The utility removes all of the PDLoginModuleWrapper entries as well as the Tivoli Access Manager authorization table entry from security.xml, effectively removing the JACC provider for Tivoli Access Manager. Backup security.xml before running this utility.

  (dist)(zos) Enter the following commands:

  install_root/java/jre/bin/java -classpath  "install_root/lib/AMJACCProvider.jar:CLASSPATH"
  com.tivoli.pd.as.jacc.cfg.CleanSecXML fully_qualified_path/security.xml

  (iseries) Enter the following commands:

  java -Djava.version=1.5 -classpath  "app_server_root/lib/AMJACCProvider.jar:CLASSPATH"
  com.tivoli.pd.as.jacc.cfg.CleanSecXML fully_qualified_path/security.xml

"HPDIA0202w: An unknown user name was presented to Access Manager"

We might encounter the following error message if you try to use an existing user in a Local Directory Access Protocol (LDAP) user registry with Tivoli Access Manager:

AWXJR0008E   Failed to create a PDPrincipal for principal mgr1.:  AWXJR0007E   A Tivoli Access Manager exception was caught. Details are:
"HPDIA0202W  An unknown user name was presented to Access Manager."

This problem might be caused by the host name exceeding predefined limits with Tivoli Access Manager when it is configured against MS Active Directory. In WebSphere Application Server, the maximum length of the host name can not exceed 46 characters.

Check that the host name is not fully qualified. Configure the machine so that the host name does not include the host domain.

To correct this error...

1. On the command line, type the following information to get a Tivoli Access Manager command prompt:
   pdadmin -a administrator_name -p administrator_password

   The pdadmin administrator_name prompt is displayed. For example:

   pdadmin -a administrator1 -p passw0rd

2. At the pdadmin command prompt, import the user from the LDAP user registry to Tivoli Access Manager by typing the following information:
   user import user_name cn=user_name,o=organization_name,c=country

   For example:

   user import jstar cn=jstar,o=ibm,c=us

After importing the user to Tivoli Access Manager, use the user modify command to set the user account to valid. The following syntax shows how to use this command:

user modify user_name account-valid yes

For example:

user modify jstar account-valid yes

For information on how to import a group from LDAP to Tivoli Access Manager, see the Tivoli Access Manager documentation.

"HPDAC0778E: The specified user's account is set to invalid"

We might encounter the following error message after you import a user to Tivoli Access Manager and restart the client:

AWXJR0008E Failed to create a PDPrincipal for principal mgr1.: AWXJR0007E A Tivoli Access Manager exception was caught. Details are: "HPDAC0778E The specified user's account is set to invalid."

To correct this error, use the user modify command to set the user account to valid. The following syntax shows how to use this command:

user modify user_name account-valid yes

For example:

user modify jstar account-valid yes

"HPDJA0506E: Invalid argument: Null or zero-length user name field for the ACL entry"

We might encounter an error similar to the following message when you propagate the security policy information from the application to the provider using the wsadmin propagatePolicyToJACCProvider command:

AWXJR0035E   An error occurred while  attempting to add member,                  cn=agent3,o=ibm,c=us, to role AgentRole
HPDJA0506E   Invalid argument: Null or zero-length user name field for                  the ACL entry

To correct this error, create or import the user, that is mapped to the security role to the Tivoli Access Manager. For more information on propagating the security policy information, see the documentation for the authorization provider.

WASX7017E: Exception received while running file "InsuranceServicesSingle.jacl"

After the JACC provider and Tivoli Access Manager are enabled, when attempting to install the application, which is configured with security roles using wsadmin, the following error might occur:

WASX7017E: Exception received while running file "InsuranceServicesSingle.jacl";  exception information: com.ibm.ws.scripting.ScriptingException: WASX7111E:  Cannot find a match for supplied option:  "[RuleManager, , , cn=mgr3,o=ibm,c=us|cn=agent3,o=ibm,c=us, cn=ManagerGro
up,o=ibm,c=us|cn=AgentGroup,o=ibm,c=us]" for task "MapRolesToUsers"

The $AdminApp MapRolesToUsers task option is no longer valid when Tivoli Access Manager is used as the authorization server. To correct the error, change MapRolesToUsers to TAMMapRolesToUsers.

Access denied exceptions accessing applications when using JACC

In the case of Tivoli Access Manager, you might see the following error message.

AWXJR0044E: The access decision for Permission, {0}, was denied because either the PolicyConfiguration or RoleConfiguration objects did not get created successfully at application installation time. RoleConfiguration exists = {false}, PolicyConfiguration exists = {"false"}.

If the access denied exceptions are not expected for the application, check the SystemOut.log files to see if the security policy information was correctly propagated to the provider.

If the security policy information for the application is successfully propagated to the provider, the audit statements with the message key SECJ0415I appear. However, if there was a problem propagating the security policy information to the provider (for example: network problems, JACC provider is not available), the SystemOut.log files contain the error message with the message keys SECJ0396E (during install) or SECJ0398E (during modification). The installation of the application is not stopped due to a failure to propagate the security policy to the JACC provider. Also, in the case of failure, no exception or error messages appear during the save operation. When the problem causing this failure is fixed, run the propagatePolicyToJaccProvider tool to propagate the security policy information to the provider without reinstalling the application.

"HPDBA0219E: An error occurred reading data from an SSL connection"

An error message (HPDBA0219E) might appear in dmgr SystemOut.log when you install an application on WebSphere Application Server Network Deployment (ND) and a managed node with Tivoli Access Manager is enabled.

If the error occurs, then the security policy data of recently deployed applications might not be immediately available. The policy data is available based on the server replicate time of the Tivoli Access Manager. This is defaulted to 30 seconds after all updates have been completed. To ensure that the latest policy data is available, log on to the pdadmin console and type: server replicate.

(zos) "There are no ports available in the port set" error might occur

When you use Tivoli Access Manager as the JACC provider and stop WebSphere Application Server using the console or the wsadmin script, there is a clean up process that runs for Tivoli Access Manager. WebSphere Application Server is unable to complete the clean up process.

WAS uses a different port number for each new process. Eventually, the application server runs out of port numbers to connect to the Tivoli Access Manager server and displays a "There are no ports available in the port set" error.

If this error occurs, you must manually clean up the ports that are available to WebSphere Application Server processes.

Related concepts

Authorization providers

Tivoli Access Manager integration as the JACC provider

JACC providers

JACC support in WebSphere Application Server

Related tasks

Troubleshooting security configurations

Enable an external JACC provider

Authorizing access to Java EE resources using Tivoli Access Manager

Propagating security policy of installed applications to a JACC provider

Interfaces that support JACC

Related information:

IBM Tivoli Access Manager for e-business information center