migrateEAR utility for ISAM

The migrateEAR utility migrates changes made to console users and groups in the admin-authz.xml and naming-authz.xmlfiles into the Security Access Manager object space.

Syntax

migrateEAR

-j fully_qualified_filename
-c pdPerm.properties_file_location
-a ISAM_admin_id
-p ISAM_admin_password
-w WAS_admin_id
-d user_registry_domain_suffix
[-r root_objectspace_name]
[-t ssl_timeout]
[-z role_mapping_location]

Notes:

• -j defaults to:
  profile_root/config/cells/cell/admin-authz.html

• -c defaults to:
  profile_root/etc/pd/PdPerm.properties

  Logging goes to:

  profile_root/logs/pdwas_migrate.log

• The -profile parameter is optional and defaults to the default profile name.

Parameters

(Windows) Attention: In the following parameters, use the absolute path instead of a variable.

-aISAM_admin_id

The administrative user identifier. The administrative user must have the privileges required to create users, objects, and access control lists (ACLs). For example, -a sec_master.

Optional. When the parameter is not specified, we are prompted to supply it at run time.

-c PdPerm.properties_file_location

The Uniform Resource Indicator (URI) location of the PdPerm.properties file configured by the pdwascfg utility. When WAS is installed in the default location, the URI is:

file:/opt/IBM/WebSphere/AppServer/java/jre/PdPerm.properties

-d user_registry_domain_suffix

The domain suffix for the user registry to use. For example, for LDAP user registries, this value is the domain suffix, such as: "o=ibm,c=us"

(Windows) Windows platforms require that the domain suffix is enclosed within quotes.

Use the pdadmin user show command to display the distinguished name (DN) for a user.

-j fully_qualified_pathname

The fully qualified path and file name of the J2EE application archive file (admin-authz.xml) or the roles definitions file (naming-authz.xml), used for a naming operation authorization. Optionally, this path can also be a directory of an expanded enterprise application. For example, when WAS is installed in the default location, the path to the data files to migrate includes:

file:/opt/IBM/WebSphere/AppServer/profiles/profile/config/cells/cell/admin-authz.xml

-p Tivoli_Access_Manager_administrator_password

The password for the ISAM administrative user. The administrative user must have the privileges required to create users, objects, and access control lists (ACLs). For example, we can specify the password for the -a sec_master administrative user as -p myPassword.

When this parameter is not specified, the user is prompted to supply the password for the administrative user name.

-r root_objectspace_name

The space name of the root object. The value is the name of the root of the protected object namespace hierarchy created for WAS policy data.

The default value for the root object space is WebAppServer.

Set the ISAM root object space name by modifying the amwas.amjacc.template.properties file prior to configuring the Java Authorization Contract for Containers (JACC) provider for ISAM for the first time. Use this option if the default object space value is not used in the configuration of the ISAM JACC provider for ISAM.

Do not change the ISAM object space name after the ISAM JACC provider is configured.

-t ssl_timeout

The number of minutes for the SSL timeout. This parameter is used to disconnect and reconnect the SSL context between the ISAM authorization server and the policy server before the default connection times out.

The default is 60 minutes. The minimum value is 10 minutes. The maximum value cannot exceed the ISAM ssl-v3-timeout value. The default value for ssl-v3-timeout is 120 minutes.

If we are not familiar with the administration of this value, we can safely use the default value.

-w WebSphere_Application_Server_administrator_user_name

The user name configured in the WAS security user registry field as the administrator. This value matches the account that we created or imported in Create the security administrative user for ISAM. Access permission for this user is needed to create or update the ISAM protected object space.

When the WAS administrative user does not already exist in the protected object space, it is created or imported. In this case, a random password is generated for the user and the account is set to not valid. Change this password to a known value and set the account to valid.

A protected object and access control list (ACL) are created. The administrative user is added to the pdwas-admin group with the following ACL attributes:

T

Traverse permission

i

Invoke permission

WebAppServer

We can overwrite the action group name. The default name is WebAppServer. This action group name and the matching root object space can be overwritten when the migration utility is run with the -r option.

-z role_mapping_location

The location where the role mapping is to be stored when migrating administration applications. The default location is to place the role mapping in the current directory structure, such as:

/WebAppServer/deployedResouces

Specify the -z option adds another directory level in which to store the role mapping. For example, if we specify -z Roles in the migrateEAR utility, the role mapping is stored in the directory structure as follows:

/WebAppServer/deployedResouces/Roles

If the -z option is specified, we must manually update the value of the com.tivoli.pd.as.rbpf.RoleContainerName property in the amwas.node.amjacc.properties, and amwas.node.authztable.properties files such that this value matches the value specified for the -z option. We do not have to restart WAS after updating the value of the com.tivoli.pd.as.rbpf.RoleContainerName propert.

Comments

This utility migrates security policy information from deployment descriptors or enterprise archive files to ISAM for WAS. The script calls com.tivoli.pdwas.migrate.Migrate the Java class.

Before invoking the script run the setupCmdLine.bat or the setupCmdLine.sh commands. These files can be found in the %WAS_HOME%/bin directory.

(iSeries) Before you invoke the script, run the setupCmdLine script from the Qshell command line. We can find this file in the profile_root/bin directory, where profile_root is the installation path. In a default installation, profile_root is app_server_rootND.

The script is dependent on finding the correct environment variables for the location of prerequisite software.

The script calls Java code with the following options:

-Dpdwas.lang.home

The directory containing the native language support libraries provided with the JACC provider for ISAM. These libraries are located in a subdirectory under the JACC provider for ISAM installation directory. For example:

-Dpdwas.lang.home=%PDWAS_HOME%\java\nls

-cp %CLASSPATH% com.tivoli.pdwas.migrate.Migrate

The CLASSPATH variable must be set correctly for our Java installation.

(Windows) Both the -j option and the -c option can reference the %WAS_HOME% variable to determine where WAS is installed. This information is used to:

• Build the full path name of the enterprise archive file.
• Build the full URI path name to the location of the PdPerm.properties file.

To enable a new user access to the administrative group in WAS, IBM recommends that the user be added to the pdwas-admin group after JACC has been enabled. We can enter the administrative primary ID (adminID) in the group. This is required when the serverID is not the same as the adminID.

The following is an example of this command:

pdadmin> group modify pdwas-admin add adminID

Return codes

The utility can return the following exit status codes:

0

The command completed successfully.

1

The command failed.

Authorizing access to administrative roles

Propagating administrative role changes to ISAM