Oracle® Fusion Middleware Application Security Guide 11g Release 1 (11.1.1) Part Number E10043-10 |
|
|
PDF · Mobi · ePub |
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.
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:
type
specifies the kind of security data being upgraded. The only valid values are xmlIdStore, xmlPolicyStore, oidPolicyStore, xmlCredStore, xmlAppPolicies, and appPolicies.
jpsConfigFile
specifies the location of a configuration file jps-config.xml
relative to the directory where the script 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.xml file relative to the directory where the script 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 script 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 the 11.1.1.2.0 jazn-data.xml file which includes resource type specifications.
dst
specifies the destination context that points to the policy store to update.
The following sections contain examples that illustrate the use of the script upgradeSecurityStore
in different scenarios:
Example 3 - Upgrading to Oracle Internet Directory LDAP-Based Policies
Example 4 - Upgrading File-Based Policies to Use the Resource Catalog
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
.
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
.
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>
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>
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:
Stop the application server.
Install new binaries.
In case of upgrading a DB-based store, use Oracle Fusion Middleware Patch Set Assistant to upgrade the DB schema as follows:
Navigate to the OPSS Schema page.
Enter data for Connect String, DBA User Name and Password, and Schema User Name and Password and then click Next.
Run upgradeOpss
as described in section Command Syntax.
Restart the application server.
Note the following points:
The offline script upgradeOpss
:
Does not change the repository type; that is, if the source policy store is of a given type, then the target policy store is of the same type.
Applies to an existing domain, which need not be recreated.
If the target store has already been updated to PS5, then running the script changes nothing.
In case of a LDAP-based store, the connection parameters to the source and target stores are read from the file jps-config.xml
or, alternatively, passed as arguments to the script.
In case of a DB-based store, the connection parameters are passed as arguments to the script.
In case the security store to be upgraded is shared by several domains (by the join operation), then all domains pointing to that store must install new PS5 binaries before the store is upgraded. Otherwise, the system may throw the exception PolicyStoreIncompatibleVersionException which indicates that the version of OPSS security store is later than the version of the OPSS binaries.
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.