migrateEAR utility for Tivoli Access Manager
The migrateEAR utility migrates changes made to console users and groups in the admin-authz.xml and naming-authz.xml files into the Tivoli® Access Manager object space.
Syntax
migrateEAR
-j fully_qualified_filename
-c pdPerm.properties_file_location
-a Tivoli_Access_Manager_administrator_ID
-p Tivoli_Access_Manager_administrator_password
-w WebSphere_Application_Server_administrator_user_name
-d user_registry_domain_suffix
[-r root_objectspace_name]
[-t ssl_timeout]
[-z role_mapping_location]
Parameters
- -aTivoli_Access_Manager_administrator_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.
This parameter is optional. When the parameter is not specified, you are prompted to supply it at run time.
- -c PdPerm.properties_file_location
- The Uniform Resource Indicator (URI) location of the PdPerm.properties file that is
configured by the pdwascfg utility. When WebSphere® Application Server is installed in the default location, the
URI is:
file:/opt/IBM/WebSphere/AppServer/java/jre/PdPerm.properties
file:/usr/IBM/WebSphere/AppServer/java/jre/PdPerm.properties
file:/"C:/Program Files/IBM/WebSphere/AppServer/java/jre/PdPerm.properties"
- -d user_registry_domain_suffix
- The domain suffix for the user registry to use. For example, for Lightweight Directory Access
Protocol (LDAP) user registries, this value is the domain suffix, such as: "o=ibm,c=us"
Windows platforms require that the domain suffix is enclosed within quotes.
You can 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 Java™ 2 Platform, Enterprise
Edition application archive file ,admin-authz.xml or the roles definitions file
naming-authz.xml that is used for a naming operation authorization. Optionally, this path
can also be a directory of an expanded enterprise application. For example, when WebSphere Application Server is
installed in the default location, the path to the data files to migrate includes:
file:/opt/IBM/WebSphere/AppServer/profiles/profile_name/config/cells /cell_name/admin-authz.xml
file:/usr/IBM/WebSphere/AppServer/profiles/profile_name/config/cells /cell_name/admin-authz.xml
"C:/Program Files/IBM/WebSphere/AppServer/profiles/profile_name/config/cells /cell_name/admin-authz.xml"
- -p Tivoli_Access_Manager_administrator_password
- The password for the Tivoli Access Manager administrative user. The administrative user must have the privileges
that are required to create users, objects, and access control lists (ACLs). For example, you 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 that is created for WebSphere Application Server policy data.
The default value for the root object space is WebAppServer.
Set the Tivoli Access Manager root object space name by modifying the amwas.amjacc.template.properties file prior to configuring the Java Authorization Contract for Containers (JACC) provider for Tivoli Access Manager for the first time. Use this option if the default object space value is not used in the configuration of the Tivoli Access Manager JACC provider for Tivoli Access Manager.
Do not change the Tivoli Access Manager object space name after the Tivoli Access Manager JACC provider is configured.
- -t ssl_timeout
- The number of minutes for the Secure Sockets Layer (SSL) timeout. This parameter is used to
disconnect and reconnect the SSL context between the Tivoli Access Manager 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 Tivoli Access Manager ssl-v3-timeout value. The default value for ssl-v3-timeout is 120 minutes.
If you are not familiar with the administration of this value, you can safely use the default value.
- -w WebSphere_Application_Server_administrator_user_name
- The user name that is configured in the WebSphere Application Server security user registry field as the
administrator. This value matches the account that you created or imported in Creating the security administrative user for Tivoli Access Manager. Access permission for this user is needed to create or update
the Tivoli Access
Manager protected object space.
When the WebSphere Application Server 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
- You 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
Specifying the -z option adds another directory level in which to store the role mapping. For example, if you specify-z Roles
in the migrateEAR utility, the role mapping is stored in the directory structure as follows:/WebAppServer/deployedResouces/Roles
Avoid trouble: If the -z option is specified, you must manually update the value of the com.tivoli.pd.as.rbpf.RoleContainerName property in the amwas.node_name.amjacc.properties, and amwas.node_name.authztable.properties files such that this value matches the value specified for the -z option. You do not have to restart WebSphere Application Server after updating the value of the com.tivoli.pd.as.rbpf.RoleContainerName property
Comments
This utility migrates security policy information from deployment descriptors or enterprise archive files to Tivoli Access Manager for WebSphere Application Server. The script calls com.tivoli.pdwas.migrate.Migrate the Java class.
Before invoking the script you must run the setupCmdLine.bat or the setupCmdLine.sh commands. These files can be found in the %WAS_HOME%/bin directory.
The script is dependent on finding the correct environment variables for the location of prerequisite software.
- -Dpdwas.lang.home
- The directory that contains the native language support libraries that are provided with the JACC provider for Tivoli Access Manager. These libraries are located in a subdirectory under the JACC provider for Tivoli Access Manager 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 your Java installation.
- 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 WebSphere Application Server, it is recommended that the user be added to the pdwas-admin group after JACC has been enabled. You can enter the administrative primary ID (adminID) in the group. This is required when the serverID is not the same as the adminID.
pdadmin> group modify pdwas-admin add adminID
Return codes
- 0
- The command completed successfully.
- 1
- The command failed.