G Upgrading Security Data

This appendix describes procedures 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), and to upgrade file-based application policies from release 11.1.1.1.0 to release 11.1.1.2.0 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

This section describes the use of the WLST command upgradeSecurityStore to upgrade application security data from previous releases to more recent ones. The details of the particular scenarios are explained below, with the various syntaxes that the command has.

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 7.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 class path. Failure to run the above script in a new shell renders the WLST commands unusable.

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"])

To upgrade XML-based application policies from release 11.1.1.1.0 to release 11.1.1.2.0, use either of the following syntaxes:

updateSecurityStore -type xmlAppPolicies
                    -srcApp applicationStripeName
                    -jpsConfigFile jpsConfigFileLocation
                    -srcJaznDataFile srcJazn
                    -dstJaznDataFile dstJazn
                    -resourceTypeFile resTypeJazn

updateSecurityStore(type="xmlAppPolicies", srcApp="applicationStripeName", jpsConfigFile="jpsConfigFileLocation", srcJaznDataFile="srcJazn", dstJaznDataFile="dstJazn", srcJaznDataFile="resTypeJazn")

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, xmlCredStore, and xmlAppPolicies.
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.

In case the type is xmlAppPolicies, the configuration file is not used to point to neither source nor destination, but to configure the audit service only. Note that the location must be passed even when the audit service is not specified in the jps-config.xml file.
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.

In case the specified type is xmlAppPolicies, it specifies the location of the application 11.1.1.1.0 jazn-data.xml file, a file that does not include resource type specifications.
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.
srcApp specifies the application stripe. It should match the application name present in the files srcJaznDataFile and resourceTypeFile. A stripe with this name is created in the file dstJaznDataFile.
dstJaznDataFile specifies the location of the application 11.1.1.2.0 jazn-data.xml file. This file includes resource type and resource instance specifications and is the replacement for the original jazn-data.xml specified in srcJaznDataFile.
resourceTypeFile specifies the location of a jazn-data.xml file which includes resource type specifications.

G.1.1 Examples of Use

The following examples illustrate the use of the command for different goals. Arguments are written in separate lines for clarity of exposition.

G.1.1.1 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 above migrates every user in the element <users>, to the XML identity store R11idStore.

G.1.1.2 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>

G.1.1.3 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: the files jps-config.xml and jazn-data.xml are located in the directory where the command is run; and 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.

G.1.1.4 Example 4 - Upgrading File-Based Policies to Use the Resource Catalog

The following invocation upgrades an application 11.1.1.1.0 file-based policy store to an application 11.1.1.2.0 file-based policy store.

updateSecurityStore -type xmlAppPolicies
                    -srcApp PolicyServlet1
                    -jpsConfigFile ./folder/jps-config.xml
                    -srcJaznDataFile ./11.1.1.1.0/jazn-data.xml
                    -dstJaznDataFile ./11.1.1.2.0/final-jazn-data.xml
                    -resourceTypeFile ./resCat/res-jazn-data.xml

The point of this upgrade is that the original 11.1.1.1.0 file does not use resource catalog elements, but the resulting 11.1.1.2.0 file does use resource type and resource instance elements.

The command basically takes the original application configuration file, along with another file specifying resource type elements, and it produces a new application configuration file that contains policies as in the original file, but modified to use resource catalog specifications.

The original and the new application configuration files provide identical behavior to the application.

The above invocation assumes that:

The source file, ./11.1.1.1.0/jazn-data.xml, contains policies for the application PolicyServlet1.
The resource type file, ./resCat/res-jazn-data.xml, contains resource type specifications for the application PolicyServlet1.
The configuration file, ./folder/jps-config.xml, is any valid configuration file that may or may not use an audit service instance. In any case, it must be specified.

The following samples illustrate the relevant portions of three data files: the input source jazn-data.xml and resource res-jazn-data.xml, and the output final-jazn-data.xml.

Input Source File jazn-data.xml

<policy-store>
  <applications>
    <application>
      <name>PolicyServlet1</name>
      <app-roles>
        <app-role>
          <name>myAppRole2</name>
          <display-name>application role myAppRole</display-name>
          <members>
            <member>
              <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
              <name>myAppRole</name>
            </member>
          </members>
        </app-role>
        <app-role>
          <name>myAppRole</name>
          <display-name>application role myAppRole</display-name>
          <members>
            <member>
              <class>
oracle.security.jps.internal.core.principals.JpsXmlEnterpriseRoleImpl</class>
              <name>developers</name>
            </member>
          </members>
        </app-role>
        <app-role>
          <name>testrole_DATA</name>
          <display-name>application role test</display-name>
          <members>
            <member>
              <class>
oracle.security.jps.internal.core.principals.JpsXmlEnterpriseRoleImpl</class>
            <name>test-entrole</name>
          </member>
        </members>
      </app-role>
      <app-role>
        <name>myAppRole_PRIV</name>
        <display-name>application role private</display-name>
        <description>app role private description</description>
        <members>
          <member>
            <class>
oracle.security.jps.internal.core.principals.JpsXmlEnterpriseRoleImpl</class>
            <name>developers</name>
          </member>
          <member>
            <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
            <name>myAppRole</name>
          </member>
        </members>
      </app-role>
    </app-roles>
    <jazn-policy>
      <grant>
        <grantee>
          <principals>
            <principal>
              <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
              <name>myAppRole_PRIV</name>
            </principal>
          </principals>
        </grantee>
        <permissions>
          <permission>
            <class>oracle.security.jps.JpsPermission</class>
            <name>getClassLoader</name>
          </permission>
          <permission>
            <class>
oracle.adf.share.security.authorization.RegionPermission</class>
            <name>dummyName</name>
            <actions>view,edit</actions>
          </permission>
        </permissions>
      </grant>
      <grant>
        <grantee>
          <principals>
            <principal>
              <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
              <name>myAppRole</name>
            </principal>
          </principals>
        </grantee>
        <permissions>
          <permission>
            <class>java.lang.XYZPermission</class>
            <name>newxyz</name>
          </permission>
        </permissions>
      </grant>
      <grant>
        <grantee>
          <principals>
            <principal>
              <class>
oracle.security.jps.internal.core.principals.JpsXmlEnterpriseRoleImpl</class>
              <name>test-entrole</name>
            </principal>
          </principals>
        </grantee>
        <permissions>
          <permission>
            <class>oracle.security.jps.JpsPermission</class>
            <name>newxy</name>
            <actions>view,edit</actions>
          </permission>
        </permissions>
      </grant>
    </jazn-policy>
  </application>
 </applications>
</policy-store>

Input Resource File res-jazn-data.xml

<jazn-data>
  <jazn-realm default="jazn.com">
  </jazn-realm>
  <policy-store>
    <applications>
      <application>
        <name>PolicyServlet1</name>
        <resource-types>
          <resource-type>
            <name>FileResourceType</name>
            <display-name>File Access</display-name>
            <description>Resource Type Modelling File Access</description>
            <provider-name>provider</provider-name>
            <matcher-class>oracle.security.jps.JpsPermission</matcher-class>
            <actions-delimiter>,</actions-delimiter>
            <actions>delete,write,read</actions>
          </resource-type>
        </resource-types>
        <jazn-policy>
        </jazn-policy>
      </application>
    </applications>
  </policy-store>
  <jazn-policy>
  </jazn-policy>
</jazn-data>

Output Data File final-jazn-data.xml

<jazn-data>
  <jazn-realm>
  </jazn-realm>
  <policy-store>
    <applications>
      <application>
        <name>PolicyServlet1</name>
        <app-roles>
          <app-role>
            <name>myAppRole2</name>
            <display-name>application role myAppRole</display-name>
            <guid>4341CC10EAFB11DE9F7F17D892026AF8</guid>
            <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
                <name>myAppRole</name>
                <guid>43428F60EAFB11DE9F7F17D892026AF8</guid>
              </member>
            </members>
          </app-role>
          <app-role>
            <name>myAppRole</name>
            <display-name>application role myAppRole</display-name>
            <guid>43428F60EAFB11DE9F7F17D892026AF8</guid>
            <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <class>weblogic.security.principal.WLSGroupImpl</class>
                <name>developers</name>
              </member>
            </members>
          </app-role>
          <app-role>
            <name>testrole_DATA</name>
            <display-name>application role test role</display-name>
            <guid>4342B670EAFB11DE9F7F17D892026AF8</guid>
            <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <class>weblogic.security.principal.WLSGroupImpl</class>
                <name>test-entrole</name>
              </member>
            </members>
          </app-role>
          <app-role>
            <name>myAppRole_PRIV</name>
            <display-name>application role private</display-name>
            <description>app role private description</description>
            <guid>4342B671EAFB11DE9F7F17D892026AF8</guid>
            <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
            <members>
              <member>
                <class>
weblogic.security.principal.WLSGroupImpl</class>
                <name>developers</name>
              </member>
              <member>
                <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
                <name>myAppRole</name>
                <guid>43428F60EAFB11DE9F7F17D892026AF8</guid>
              </member>
            </members>
          </app-role>
        </app-roles>
        <resource-types>
          <resource-type>
            <name>FileResourceType</name>
            <display-name>File Access</display-name>
            <description>Resource Type Modelling File Access</description>
            <provider-name>provider</provider-name>
            <matcher-class>oracle.security.jps.JpsPermission</matcher-class>
            <actions-delimiter>,</actions-delimiter>
            <actions>delete,write,read</actions>
          </resource-type>
        </resource-types>
        <resources>
          <resource>
            <name>getClassLoader</name>
            <type-name-ref>FileResourceType</type-name-ref>
          </resource>
          <resource>
            <name>newxy</name>
            <type-name-ref>FileResourceType</type-name-ref>
          </resource>
        </resources>
        <jazn-policy>
          <grant>
            <grantee>
              <principals>
                <principal>
                  <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
                  <name>myAppRole_PRIV</name>
                  <guid>4342B671EAFB11DE9F7F17D892026AF8</guid>
                </principal>
              </principals>
            </grantee>
            <permissions>
              <permission>
                <class>oracle.security.jps.JpsPermission</class>
                <name>getClassLoader</name>
              </permission>
              <permission>
                <class>
oracle.adf.share.security.authorization.RegionPermission</class>
                <name>dummyName</name>
                <actions>view,edit</actions>
              </permission>
            </permissions>
            <permission-set-refs>
            </permission-set-refs>
          </grant>
          <grant>
            <grantee>
              <principals>
                <principal>
                  <class>
oracle.security.jps.service.policystore.ApplicationRole</class>
                  <name>myAppRole</name>
                  <guid>43428F60EAFB11DE9F7F17D892026AF8</guid>
                </principal>
              </principals>
            </grantee>
            <permissions>
              <permission>
                <class>java.lang.XYZPermission</class>
                <name>newxyz</name>
              </permission>
            </permissions>
            <permission-set-refs>
            </permission-set-refs>
          </grant>
          <grant>
            <grantee>
              <principals>
                <principal>
                  <class>
weblogic.security.principal.WLSGroupImpl</class>
                  <name>test-entrole</name>
                </principal>
              </principals>
            </grantee>
            <permissions>
              <permission>
                <class>oracle.security.jps.JpsPermission</class>
                <name>newxy</name>
                <actions></actions>
              </permission>
            </permissions>
            <permission-set-refs>
            </permission-set-refs>
          </grant>
        </jazn-policy>
      </application>
    </applications>
  </policy-store>
  <jazn-policy>
  </jazn-policy>
</jazn-data>