Administrative Reference

Import/Export Utilities

This section provides detailed information about tools used to import/export data from the database:

PolicyIX

The Policy Propagation Import/Export (policyIX) tool can be used to import and export policies and also export SSM configurations — it does not support importing SSM configurations. It is commonly used to move policy data from one database to another and to export an SSM configuration to an XML file for use when the SSM is deployed without an SCM.

SSL Requirements

To sign exported configuration files, PolicyIX uses the SSL infrastructure specified during the Administration Server installation, . Specifically, the policyIX.bat file invokes the tool with -Dales.policyTool.signer=wles-admin. The ales.policyTool.signer property is a required Java property that specifies the alias of the signing key in the identity keystore, which must be equal to the Administration server machine name.

The public key of the Administration Server is then retrieved from the SSL peer keystore for the purpose of validating the configuration file’s signature. This public key is available from the Administration Server’s certificate that was added to the SSL peer keystore during the enrollment process.

The unencoded signature of the XML file is stored in a corresponding signature file, whose name is derived from the full name of the signed XML file (including extension) with the added .sig extension. For example, myconfig.xml.sig.

After you export the configuration data, you must manually copy the XML configuration file and signature file to the SSM configuration directory, BEA_HOME/ales32-ssm/<ssm-type>/instance-name/config.

If you do not use the default name (wles.securityrealm.xml) for the configuration file, set the wles.realm.filename property in the SSM instance’s /config/security.properties file. See the SSM Installation and Configuration Guide for additional information about the security.properties file.

Requirements and Limitations

Export an SSM Configuration

Use the following command to export an SSM configuration:

policyIX.bat <config_id> -exportConfig <config.xml> <exportfile.xml> -passwdPrompt

For example, the following command exports a SSM configuration named java2ssm to a file named java2ssmconfig.xml.

policyIX.bat java2ssm -exportConfig ..\config\policyIX_config.xml java2ssmconfig.xml

Export Policies

Use the following command to export policies from the database to an XML file:

policyIX.bat -export <config.xml> <exportfile.xml> -passwdPrompt

Import Policies

Use the following command to load policies from an XML file to the database:

policyIX.bat -import -disableTransaction <config.xml> <importfile.xml> -passwdPrompt

PolicyIX Configuration File

Table 3-1 describes the possible elements in the policyIX configuration file.

XML Policy Data Files

When using policyIX to import policies, the policies to be imported must be specified in the required XML format. This section describes the required format and provides an example.

In addition to the information provided here, there are two ways understand the XML requirements:

Importing a Role Policy

The XML shown in Figure 3-1 could be used to import the following policies:

grant(//role/myrole, //resources/myresource, //MyOrg/MyDir/RJones/) if true;

grant( post, //myresource, //role/myrole/) if true;

<?xml version="1.0" encoding="UTF-8"?>
<xb:policy_propagation xmlns:xb="http://policypropagation.ales.com/xmlbean">
<xb:policy_propagation_data_v2>
  <xb:scopes>
    <xb:application_entry value="RootOrg!MyOrg!MyApp">
       <xb:resources>
          <xb:resource_entry value="//resources/myresource"/>
       </xb:resources>
       <xb:actions>
          <xb:action_entry value="post"/>
       </xb:actions>
       <xb:roles>
          <xb:role_entry value="myrole" parent=""/>
       </xb:roles>
       <xb:policies>
         <xb:membership_rule_entry>
            xb:policy_effect value="grant"/>
            xb:policy_roles>
                <xb:policy_role_entry value="myrole"/>
            </xb:policy_roles>
            <xb:policy_resources>
              <xb:policy_resource_entry value="//resources/myresource"/>
            </xb:policy_resources>
            <xb:policy_subjects>
             <xb:policy_user_entry name="RJones" directory="MyDir" scope="MyOrg"/>
            </xb:policy_subjects>
         </xb:membership_rule_entry>
         <xb:authorization_policy_entry>
           <xb:policy_effect value="grant"/>
           <xb:policy_actions>
               <xb:policy_action_entry value="post"/>
           </xb:policy_actions>
           <xb:policy_resources>
              <xb:policy_resource_entry value="//resources/myresource"/>
            </xb:policy_resources>
            <xb:policy_subjects>
              <xb:policy_role_entry value="myrole"/>
            </xb:policy_subjects>
         </xb:authorization_policy_entry>
                </xb:policies>
    </xb:application_entry>
    </xb:scopes>
</xb:policy_propagation_data_v2>
</xb:policy_propagation>

Table 3-2 describes the XML elements used in the above example.

Modify Policy Propagation Servlet

By default, policyIX on WebLogic Server 8.15 supports the export of configuration data — but not policy data. This section describes how to manually modify the policy propagation servlet so that policyIX will also import/export policy data.

Policyexporter

Policyexporter is used to output data from the policy store to plain-text policy files. These policy files can be imported back to the same or to another policy store using the policyloader as described in Policyloader.

The plain-text policy files include the following management object types:

— Resources, resource attributes, and resource bindings
— Actions, action bindings, and action groups
— Roles
— Authorization and role policies
— Identities, including user, group, and membership
— Declarations, constants and evaluation functions
— SSM configuration data and providers' configuration data

The export process also generates two additional files (object_config, objattr_config) that contain SSM configuration data. These files also get loaded and are similar to object and objattr respectively in format. These files are split so as to differentiate policy elements from configuration elements. However, object_config and objattr_config can be merged into object and objattr respectively, if needed.

Requirements and Limitations

Observe the following requirements and limitations:

Performing a Policy Export

To perform a policy export using policyexporter:

Running Policyexporter

To run policyexporter, perform the following steps:

Policyloader

The Policy Import tool (policyloader.bat|sh) is a Java utility that can be used to import and export policy data. To import policies, it reads text files containing the policy definitions — each policy element is stored in a separate file, referred to as a policy file. For information on the specific format of these policy elements, see Advanced Topics in the Policy Managers Guide.

PolicyIX imports/exports support the following objects:

— Organizations and Identities
— Applications
— Resources and resource attributes
— Actions including action groups
— Declarations, including attribute definitions, evaluation functions, and constants.
— Roles, role hierarchies, role attributes
— Policies including Membership Rules and Authorization policies
— Resource binding
— SSM configuration (export only)
— Meta objects

Policyloader uses multi-threading processing and is optimized for fast imports and distribution of large policies. In addition, policy imports are transactional: all policies are loaded, or none.

Requirements and Limitations

Performing a Policy Import

To perform a import using policyloader:

Policyloader Configuration File

The configuration file consists of name/value pairs specifying information needed by policyloader. The file paths in the configuration file depend on the directory from which you run the Policy Import tool. You may use the full path filename to avoid directory dependency. Spaces are allowed between parameters and between new lines. Parameter names are case insensitive. Table 3-3 lists the parameters you need to configure for the Policy Import tool.

A sample file configuration file is shown in Policyloader Configuration File.

Sample Configuration File

Listing 3-1 provides sample configuration file.

# Copyright (c) 2004-2008 Oracle and/or its affiliates. All rights reserved.
#####################################################################

## In addition, asi.properties is read in from the /config directory.  Parameters set here will override values defined there.
#### Enterprise Domain Name (DEPRICATED - Should always be asi)
Domain asi

#### A OES admin user name. Must be the same as stored in database.
Username admin

#### Encrypted password file
PasswordFile C:/bea/ales32-shared/keys/password.xml

#### Password key file
PasswordKeyFile C:/bea/ales32-shared/keys/password.key

#### The application node holding the administration policy.
#### If commented out it assumes the dafult value of "admin".
ApplicationNode admin

#### Milliseconds to wait for server to respond. For large files 
#### increase or use ASI.INFINITE
RequestTimeout 600000

#### Number of times retries should take place(DEFAULT 100)
BLMContextRetries 10

#### Milliseconds to wait between retries (DEFAULT 100ms)
BLMContextInterval_ms 10000

#### Number of concurrent threads.
RunningThread 2

#### Number of entries loaded in a single load (200 here)
BulkSize 200

#### Directory of policy files. May be a relative path.
PolicyDirectoryPath C:/bea/ales32-admin/data/adminPolicy/standardBase

#### Indicate if policies should be distributed. Default = YES
PolicyDistribution flush

#### File where all error messages are logged.
ErrorLogFile C:/bea/ales32-admin/log/loader.log

#### Action to be performed: load or remove.  Default = LOAD
#Action REMOVE

#### Policy import mode: INITIAL or RECOVER. Default = INITIAL
#### This parameter can also be passed in as a command parameters.
#### Command line parameters override values in this file.
#Mode RECOVER

#### Uncomment to see debug information, default = 0 (no debug)
#Debug 1

#### Uncomment to hide console interaction (yes/no), default = yes
#### If you want to run loader in background/in batch process, set this to no
ConsoleDisplay no

Running Policyloader

Once the configuration file and the policy data files are set up, run policyloader follows:

Check for Errors

If an error occurs, the Policy Loader terminates; you must restart the Policy Import tool. The name of the error file is defined in the your Policy Import tool configuration file by the ErrorLogFile parameter. In addition, to distribute policy you need distribution privileges granted to you.

Also, because the Policy Import tool is multi-threaded and each thread writes out to the log when it is complete, you cannot guarantee the order in which each load completes.

The Policy Import tool processes policy files according to a predefined order, and if the policy file is not found, it tries to load the next policy file in the proper order. Records imported successfully are committed to the database. After the import process begins, you cannot go back within the same process and edit changes you have made. If you want to change what you have done, you have to start a new import process. After the import process is complete, you may run the removal operation to reverse the import process.

Recover Mode

When the policyloader encounters an error (other than Object Exists Error), it generates a file named <filename>.<version> (for example, object.1 , object.2) and logs an error message. These files contain only the problematic lines from policy data files. You can now correct the mistakes in these files and re-run the policy loader in the recover mode.

Recover mode can be run in one of two ways:

In recovery mode, policyloader will only try to load the highest version files that have not already been loaded. If you corrected priv.1 and there are still problems, then the loader will generate priv.2 with just the lines that failed. You can then correct priv.2 and rerun the policy loader in the recover mode. Perform additional iterations until policyloader does not generate any new version files and the error log file does not indicate any outstanding errors.

Load_Adminpolicy

Loads the administrative policy that determines administrative access to access the Administration Console and Entitlements Administration Application. This utility is automatically called during the installation process and it is unlikely you will ever need to run it independently.

Usage

OES_ADMIN_HOME\bin\load_adminpolicy.bat

Example

load_adminpolicy.bat