Skip Headers
Oracle® Fusion Middleware Application Security Guide
11g Release 1 (11.1.1)

Part Number E10043-12
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

G Upgrading Security Data

This appendix describes several procedures to update security data. Specifically, it describes how to upgrade security data from a major release (10.1.3.x) to a major release (11.1.1), and how to upgrade data from a minor release (11g OPSS PS1, PS2, PS3 or PS4) to 11g OPSS PS5, in the following sections:

If upgrading from 11gR1 to 11gR1 PS1:

For details about this upgrade combination, see section Special Instructions for Oracle Fusion Middleware 11g Release 1 (11.1.1.1.0) in Oracle Fusion Middleware Installation Planning Guide.

For an overview and details about Identity Management upgrade, see Oracle Fusion Middleware Upgrade Guide for Oracle Identity Management.

G.1 Upgrading with upgradeSecurityStore

The OPSS script upgradeSecurityStore is used only to upgrade application security data from a previous major release (such as 10.1.1.3) to more recent one (such as 11.1.1.1). To upgrade between minor 11g releases, use upgradeOpss as described in section Upgrading Policies with upgradeOpss.

If the target of the upgrading is an LDAP-based repository, then some setting up before running the script is required, as described in Section 8.2.2, "Prerequisites to Using an LDAP-Based Security Store."

The script is offline, that is, it does not require a connection to a running server to operate, and can be run in interactive mode or in script mode, on WebLogic, and in interactive mode only, on WebSphere. In interactive mode, you enter the script at a command-line prompt and view the response immediately after. In script mode, you write scripts in a text file and run it without requiring input, much like the directives in a shell script.

For platform-specific requirements to run an OPSS script, see Important Note.

Script and Interactive Modes Syntaxes

The script 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 file-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")
                     

To upgrade 11.1.1.1.0 application policies to 11.1.1.2.0 format, use either of the following syntaxes:

updateSecurityStore -type appPolicies
                    -srcApp applicationStripeName
                    -jpsConfigFile jpsConfigFileLocation
                    -dst dstContext
                    [-resourceTypeFile resTypeJazn]

updateSecurityStore(type="appPolicies", srcApp="applicationStripeName", jpsConfigFile="jpsConfigFileLocation", dst="dstContext" [, resourceTypeFile="resTypeJazn"])
                     

This upgrade works in-place and involves the creation of specified resource types and resources corresponding to permissions in the grants.

Once the run completes, the policy store pointed to by the context passed in dst in the configuration file passed in jpsConfigFile has new resource types and new resources defined for application passed in srcApp. The resource types are read from the file specified in resourceTypeFile and resources are created corresponding to permissions in the application grants.

The meaning of the arguments is as follows:

G.1.1 Examples of Use

The following sections contain examples that illustrate the use of the script upgradeSecurityStore in different scenarios:

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 script assumes that: (a) the files jps-config-idstore.xml and jazn-data.xml are located in the directory where the script 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 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 script assumes that: the files jps-config.xml and jazn-data.xml are located in the directory where the script 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.3 Example 3 - Upgrading to Oracle Internet Directory LDAP-Based Policies

The following invocation illustrates the upgrading 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.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 script 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>

G.2 Upgrading Policies with upgradeOpss

upgradeOpss is an offline script that updates PS1, PS2, PS3 or PS4 configurations and stores to a PS5 configuration and store.

The store to be upgraded can be file-, LDAP-, or DB-based and possibly be shared by several WebLogic domains, and the script upgrades system policies, application policies, and the file jps-config.xml.

The OPSS binaries and the target policy store must have compatible versions; for details, see Section L.21, "Incompatible Versions of Binaries and Policy Store."

Important Notes:

upgradeOpss must be run on the system that hosts the administration server instance so that when the server comes up, the upgraded data is pushed to all managed servers in the cluster.

Before using it, make sure that you backup the store to be upgraded. In case of a LDAP store, backup all data under the root node of the store (which is specified as a property of the store in the configuration file). In case of an upgrade failure, restore that node entirely. For details about backing up, see the documentation for your specific LDAP store.

To upgrade from PS1, PS2, PS3 or PS4 to PS5, proceed as follows:

  1. Stop the application server.

  2. Install new binaries.

  3. In case of upgrading a DB-based store, use Oracle Fusion Middleware Patch Set Assistant to upgrade the DB schema as follows:

    1. Navigate to the OPSS Schema page.

    2. Enter data for Connect String, DBA User Name and Password, and Schema User Name and Password and then click Next.

  4. Run upgradeOpss as described in section Command Syntax.

  5. Restart the application server.

Note the following points:

G.2.1 Command Syntax

To upgrade a file-, LDAP-, or DB-based store, use the syntax below; note that the connection arguments are not required in case of a file-based store; are optional in case of an LDAP-based store; and are required in case of a DB-based store:

upgradeOpss(jpsConfig="<full path to the old version jps config file>",
            jaznData="<full path to the new version OOTB JAZN data file>",
            [auditStore="<full path to the OOTB audit-store.xml file>"],
            [jdbcDriver="<jdbc driver>", 

             url="<jdbc-ldap url>", 
             user="<jdbc-ldap user>", 
             password="<jdbc-ldap password>"],

The meaning of the arguments is as follows:

  • jpsConfig specifies the full path to the location of the PS1, PS2, PS3 or PS4 jps-config.xml configuration file, which the scripts backs up in the same directory as a file with the suffix .bak appended to the its name; required.

  • jaznData specifies the full path to the location of the PS5 out-of-the-box system-jazn-data.xml file; required.

  • auditStore specifies the full path to the location of the PS5 out-of-the-box audit-store.xml file; optional; if unspecified, defaults to the file audit_store.xml.

  • jdbcDriver specifies the JDBC driver to the store; optional in case of LDAP-based store; required in case of DB-based store.

  • url specifies the JDBC URL or LDAP URL in the format driverType:host:port:sid; required in both DB- or LDAP-based store; if not passed, it is read from the configuration file.

  • user specifies the JDBC user name or LDAP bind name; optional in case of LDAP-based store; required in case of DB-based store; if not passed, it is read from the configuration file. In case of LDAP-based store, the user performing the upgrade must have read and write privileges to the schema, the root node, and all nodes under cn=OPSS,cn=OracleSchemaVersion; in case of a DB-based store, perform the upgrade as the OPSS DB schema user.

  • password specifies the password of the passed user; that is, the JDBC password, in case of a DB-based store, or the JDBC bind password, in case of a LDAP-based store; optional in case of LDAP-based store; required in case of DB-based store; if not passed, it is read from the configuration file.