G Upgrading Security Data

This appendix describes the procedure to update JAZN security data used in release 10.1.3.x to security data used by OPSS in release 11g Release 1 (11.1.1) using the offline WLST command upgradeSecurityStore, which allows the separate upgrading of identity, policy, or credential data.

Upgrading from 11gR1 to 11gR1 PS1:

Upgrading details are documented in section Special Instructions for Oracle Fusion Middleware 11g Release 1 (11.1.1.1.0) in Oracle Fusion Middleware Installation Planning Guide.

G.1 Upgrading Security Data

OPSS replaces JAZN (which existed in 10.1.3.x. JAZN to store identities and policies) and old data in JAZN can be upgraded to OPSS as described in this section.

If the target of the upgrading is an LDAP-based repository, then some setting up before the command is used is required, as described in Section 8.1.2, "Prerequisites to Using an LDAP-Based Policy Store."

The commands listed below are offline (that is, they do not require a connection to a running server to operate) and can be run in interactive mode or in script mode. In interactive mode, you enter the command at a command-line prompt and view the response immediately after. In script mode, you write commands in a text file (with a py file name extension) and run it without requiring input, much like the directives in a shell script.

Important:

Before invoking a security-related WLST command in a shell, you must run the script wlst.sh, as illustrated in the following sample:

> sh $ORACLE_HOME/common/bin/wlst.sh

This ensures that the required JARs are added to the classpath. Failure to run the above script in a new shell renders the WLST commands unusable.

Note:

To prevent security vulnerabilities during the upgrade, enable an SSL transmission between Oracle Containers for Java EE and Oracle HTTP Server.

Script and Interactive Modes Syntaxes

The command syntax varies depending on the type of store being upgraded. Optional arguments are enclosed in square brackets; arguments in script mode syntax are written in separate lines for clarity of exposition.

To upgrade 10.1.3.x XML identity data to 11g Release 1 (11.1.1) XML identity data, use either of the following syntaxes:

updateSecurityStore -type xmlIdStore
                    -jpsConfigFile jpsConfigFileLocation
                    -srcJaznDataFile srcJazn
                    -srcRealm jaznRealm
                    [-dst dstJpsContext]

updateSecurityStore(type="xmlIdStore", jpsConfigFile="jpsConfigFileLocation", srcJaznDataFile="srcJazn", srcRealm="jaznRealm", [dst="dstJpsContext"])

To upgrade a 10.1.3.x XML policy data to 11g Release 1 (11.1.1) XML policy data, use either of the following syntaxes:

updateSecurityStore -type xmlPolicyStore
                    -jpsConfigFile jpsConfigFileLocation
                    -srcJaznDataFile srcJazn
                    [-dst dstJpsContext]

updateSecurityStore(type="xmlPolicyStore", jpsConfigFile="jpsConfigFileLocation", srcJaznDataFile="srcJazn", [dst="dstJpsContext"])

To upgrade a 10.1.3.x Oracle Internet DirectoryLDAP-based policy data to 11g Release 1 (11.1.1) XML policy data, use either of the following syntaxes:

updateSecurityStore -type oidPolicyStore
                    -jpsConfigFile jpsConfigFileLocation
                    -srcJaznConfigFile srcJazn
                    [-dst dstJpsContext]

updateSecurityStore(type="oidPolicyStore", jpsConfigFile="jpsConfigFileLocation", srcJaznConfigFile="srcJazn", [dst="dstJpsContext"])

The meaning of the arguments (all required except for dst) is as follows:

type specifies the kind of security data being upgraded. The only valid values are xmlIdStore, xmlPolicyStore, oidPolicyStore, or xmlCredStore.
jpsConfigFile specifies the location of a configuration file jps-config.xml relative to the directory where the command is run. The target store of the upgrading is read from the context specified with the argument dst.
srcJaznDataFile specifies the location of a 10.1.3.x jazn data file relative to the directory where the command is run. This argument is required if the specified type is xmlIdStore, xmlPolicyStore, or xmlCredStore.
srcJaznConfigFile specifies the location of a 10.1.3.x jazn configuration file relative to the directory where the command is run. This argument is required if the specified type is oidPolicyStore.
users specifies a comma-delimited list of users each formatted as realmName/userName. This argument is required if the specified type is xmlCredStore.
srcRealm specifies the name of a realm in the file passed to the argument srcJaznDataFile that identifies the identities to be migrated. This argument is required if the specified type is xmlIdStore.
dst specifies the name of a jpsContext in the file passed to the argument jpsConfigFile where the destination store is configured. Optional. If unspecified, it defaults to the default jpsContext.

G.1.1 Examples of Use

In the following examples, arguments are written in separate lines for clarity of exposition.

Example 1 - Upgrading Identities

The following invocation illustrates the migration of 10.1.3 file-based identities to an 11g Release 1 (11.1.1) file-based identity store:

upgradeSecurityStore -type xmlIdStore 
                     -jpsConfigFile jps-config-idstore.xml
                     -srcJaznDataFile jazn-data.xml
                     -srcRealm jazn.com

This use of the command assumes that: (a) the files jps-config-idstore.xml and jazn-data.xml are located in the directory where the command is run; (b) the default jpsContext in the file jps-config-idstore.xml references the target identity store; and (c) the file jazn-data.xml contains a realm named jazn.com.

Here are the relevant excerpts of the two files involved in the use sample above:

<!-- excerpt from file jps-config-idstore.xml -->  
<serviceProviders>
   <serviceProvider name="R11idstore" class="oracle.security.jps.internal.idstore.xml.XmlIdentityStoreProvider" type="IDENTITY_STORE">
     <description>11g XML-based IdStore</description>
   </serviceProvider>
</serviceProviders>
...
<serviceInstances>
  <serviceInstance name="idstore.xml1" provider="R11idstore" location="./jazn-data-11.xml">
    <property name="subscriber.name" value="jazn.com"/>
    <property name="jps.xml.idstore.pwd.encoding" value="OBFUSCATE"/>
  </serviceInstance>
</serviceInstances> 
...
<jpsContexts default="default">
   <jpsContext name="default">
      <serviceInstanceRef ref="idstore.xml1" />
   </jpsContext>
</jpsContexts>

<!-- excerpt from jazn-data.xml -->
<jazn-realm>
          <realm>
                <name>jazn.com</name>
                    <users> ... </users>
    <roles> ... </roles>
  </realm>
</jazn-realm>

Thus, the sample invocation migrates every user in the element <users>, to the XML identity store R11idStore.

Example 2 - Upgrading to File-Based Policies

The following invocation illustrates the migration of a 10.1.3 file-based policy store to an 11g Release 1 (11.1.1) policy store:

upgradeSecurityStore -type xmlPolicyStore 
                     -jpsConfigFile jps-config.xml
                     -srcJaznDataFile jazn-data.xml
                     -dst destContext

This use of the command assumes that: (a) the files jps-config.xml and jazn-data.xml are located in the directory where the command is run; and (b) the file jps-config.xml contains a jpsContext named destContext.

Here are the relevant excerpts of the two files involved in the use sample above:

<!-- excerpt from file jps-config.xml -->
<serviceProviders>
  <serviceProvider type="POLICY_STORE" name="policystore.xml.provider" class="oracle.security.jps.internal.policystore.xml.XmlPolicyStoreProvider">
  <description>R11 XML-based PolicyStore Provider</description>
        </serviceProvider>
</serviceProviders>
...
<serviceInstances>
  <serviceInstance name="policystore1.xml" provider="policystore.xml.provider">
  <property name="R11PolStore" value="jazn-data1.xml"/>
</serviceInstance>
...
<jpsContexts default="default1">
   <jpsContext name="default1"> ... </jpsContext>
   <jpsContext name="destContext">
       ...
       <serviceInstanceRef ref="policystore1.xml"/>
   </jpsContext>
</jpsContexts>

<!-- excerpt from jazn-data.xml -->
<jazn-realm>
          <realm>
                ...
    <roles> ... </roles>
  </realm>
</jazn-realm>
...
<jazn-policy> ... </jazn-policy>

Thus, the sample invocation above migrates every role in the element <roles> and every policy in the element <jazn-policy> to the XML policy store R11PolStore.

Example 3 - Upgrading to Oracle Internet Directory LDAP-based Policies

The following invocation illustrates the migration of a 10.1.4 Oracle Internet Directory LDAP-based policy store to an 11g Release 1 (11.1.1) Oracle Internet Directory LDAP-based policy store:

upgradeSecurityStore -type oidPolicyStore 
                     -jpsConfigFile jps-config.xml
                     -srcJaznConfigFile jazn.xml
                     -dst destContext

The assumptions about the location of the two XML files involved in this example are similar to those in Example 2. In addition, it is assumed that (a) the file jps-config.xml contains the jpsContext destContext that points to the target Oracle Internet Directory LDAP-based policy store; and (b) the file jazn.xml describes the location of the Oracle Internet Directory LDAP server from where the policies are migrated.

Here is the relevant excerpt from the file jazn.xml:

<jazn provider="LDAP" location="ldap://myCompany.com:3843">
   <property name="ldap.user" value="cn=orcladmin"/>
   <property name="ldap.password" value="!welcome1"/>
   <property name="ldap.protocol" value="no-ssl"/>
   <property name="ldap.cache.policy.enable" value="false"/>
   <property name="ldap.initctx" value="com.sun.jndi.ldap.LdapCtxFactory"/>
</jazn>