Oracle® Fusion Middleware Security and Administrator's Guide for Web Services 11g Release 1 (11.1.1.5) B32511-05 |
|
![]() Previous |
![]() Next |
This chapter describes how to migrate Web service applications between environments, such as from development or test to production. It includes the following sections:
To migrate Web service applications independently between environments, such as from test to production, or in a scaled clustered environment, you must export the policies and the deployment configuration information to the new environment so that you can deploy the application. Depending on your configuration, you may also need to migrate policy configuration artifacts and policy assertion templates.
A deployment descriptor is an XML file that contains the basic deployment configuration for an application. For WebLogic Server and WebLogic Java EE Web services applications, you create a deployment plan that contains the necessary deployment descriptors for deploying the application in a new environment.
For ADF Business Components and WebCenter services, however, run-time policy changes are persisted in proprietary deployment descriptor (PDD) files: oracle-webservices.xml and oracle-webservices-client.xml. Because these files are not included in the WebLogic deployment plan or exported with any other deployment descriptors, you must export and import these PDD files separately. You must also export and import these PDD files separately if you are scaling your application in a clustered environment.
Note that the following Oracle Infrastructure Web services components provide different configuration management mechanisms.
For a SOA composite, Web services and Oracle WSM configurations are persisted in a composite.xml file which is included in a configuration plan used for deployment configuration. The SOA framework provides its own mechanism for composite services and configuration lifecycle and synchronizations.
ADF Web Service data control configuration stores connection details for WebCenter services in a connections.xml file and all post-deployment changes as customizations in the Metadata Services (MDS) repository.
The general steps for migrating a Web service application from a development or test environment to a production environment are as follows:
Install and configure the production environment with the components that you need.
Migrate security information, such as users and groups, the identity and policy stores, and credentials. For more information, see "Migrating Policy Configuration".
Migrate policies and deployment configuration data as required. For more information, see "Migrating Policies" and "Migrating Deployment Descriptors". Modify any information that is specific to the new environment such as host name or ports.
Deploy the applications in the new environment.
For information about migrating Fusion Middleware applications between environments, see "Advanced Administration: Expanding Your Environment" in Oracle Fusion Middleware Administrator's Guide.
The following steps describe a typical scenario for how to create a policy and migrate the policy horizontally through the different stages of the application development and deployment cycles.
Use Oracle Enterprise Manager Fusion Middleware Control to create a policy.
For more information, see "Creating Web Service Policies".
Export the policy to a file.
For more information, see "Migrating Policies".
Copy the policy file to policy store location in the Oracle JDeveloper environment.
Create a Web service in Oracle JDeveloper and attach the policy to the Web service.
For more information, see "Using Policies with Web Services" in the "Developing with Web Services" section of the JDeveloper online help.
Deploy the Web service to the staging server, and test the Web service.
For more information, see "Developing Web Services" in the JDeveloper online help.
Import the policy to the production server environment.
For more information, see "Migrating Policies".
Migrate the following information, as required:
Policy configuration. See "Migrating Policy Configuration".
Assertion templates. See "Migrating Assertion Templates".
Deploy the application into the production environment, and test the Web service.
See "Deploying Web Services Applications" and "Testing Web Services".
The following sections provide sample use cases for ADF Business Control or WebCenter Web Service applications for which you must migrate the PDD files.
The following steps describe a sample use case for scaling a deployed ADF Business Control or WebCenter Web service application within a cluster.
Deploy an ADF Business Control or WebCenter Web service application in a clustered WebLogic Server domain consisting of, for example, an Administration Server and two Managed Servers (MServer1 and MServer2). For deployment information, see Chapter 5, "Deploying Web Services Applications."
Using Fusion Middleware Control or WLST, modify the policy configuration. For example, attach a policy named oracle/wss_username_token_service_policy to the Web service on MServer2. For more information, see Chapter 8, "Attaching Policies to Web Services."
The configuration changes are persisted in the PDD files.
Restart the application.
Export the PDD to a JAR file using the exportJRFWSApplicationPDD
command. For more information, see "Migrating Deployment Descriptors".
Using the WebLogic Server Administration Console, clone a new Managed Server named MServer3 in the cluster from MServer2. For more information, see "Clone Servers" in the WebLogic Server Administration Server Online Help.
Start the new Managed Server, MServer3.
Note that MServer3 does not have the policy oracle/wss_username_token_service_policy attached because it was attached after the application was initially deployed.
Import the JAR file containing the Oracle WSM PDD files that you created in step 4 to MServer3 using the importJRFWSApplicationPDD
command. For more information, see "Migrating Deployment Descriptors".
Restart the application.
The following steps describe a sample use case for propagating run-time policy changes for an ADF Business Control or WebCenter Web service application to all servers in a cluster.
Deploy an ADF Business Control or WebCenter Web service application in a clustered WebLogic Server domain consisting of, for example, an Administration Server and three Managed Servers (MServer1, MServer2, and MServer3). For deployment information, see Chapter 5, "Deploying Web Services Applications."
Using Fusion Middleware Control or WLST, modify the policy configuration. For example, detach all policies from MServer2. For more information, see Chapter 8, "Attaching Policies to Web Services."
The configuration changes are persisted in the PDD files.
Restart the application.
Export the PDD files from MServer2 to a JAR file using the exportJRFWSApplicationPDD
command. For more information, see "Migrating Deployment Descriptors".
Use the savePddToAllAppInstancesInDomain
command, with the restartApp
argument set to true
. For more information, see "Migrating Deployment Descriptors"
The policies are now detached from all server instances in the domain and the application is restarted.
You can export individual policies from Oracle Enterprise Manager Fusion Middleware Control. You can then copy the policy to a directory or import the policy to move it to another repository.
For details about exporting and importing policies using Fusion Middleware Control, see the following sections in "Managing Web Service Policies":
Alternatively, you can use the exportRepository
and importRepository
WLST commands to export and import the policies. The following describes the steps required:
To migrate policies using WLST commands:
Export the Oracle WSM policies to a supported archive file, such as a zip file, using the exportRepository
command.
For example, to export all Oracle WSM policies to an archive named policies.zip, enter the following:
wls:/jrfServer_domain/serverConfig> exportRepository('/tmp/policies.zip',['policies:oracle/%'])
Exporting "/policies/oracle/binding_authorization_denyall_policy"
Exporting "/policies/oracle/binding_authorization_permitall_policy"
Exporting "/policies/oracle/binding_permission_authorization_policy"
.
.
.
Exporting "/policies/oracle/wss_username_token_over_ssl_service_policy"
Exporting "/policies/oracle/wss_username_token_service_policy"
Successfully exported "84" documents.
Optionally, you can edit the archive after it has been created. If, for example, you do not want to migrate all the policies to the new environment, you can manually remove them from the archive.
Move the archive to the new machine. Ensure that the Oracle WSM Policy Manager is deployed on the new machine.
Import the Oracle WSM policies using the importRepository
command. For example, to import the policies exported in the previous step:
wls:/jrfServer_domain/serverConfig> importRepository('/tmp/policies.zip')
Importing "META-INF/policies/oracle/binding_authorization_denyall_policy"
Importing "META-INF/policies/oracle/binding_authorization_permitall_policy"
Importing "META-INF/policies/oracle/binding_permission_authorization_policy"
.
.
.
Importing "META-INF/policies/oracle/wss_username_token_over_ssl_service_policy"
Importing "META-INF/policies/oracle/wss_username_token_service_policy"
Successfully imported "84" documents
For more information about these WLST commands, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.
The following sections describe how to migrate the configuration artifacts for Oracle WSM policies. Sections include:
If you are using message protection policies, you need to migrate your keystores. To migrate keystores:
Manually copy your keystores to the new environment.
For Java SE applications, copy the keystore to a user-defined location. For Java EE applications, copy the keystore to the same directory as the jps-config.xml file, namely DOMAIN_HOME/config/fmwconfig.
By default, the keystore is named default-keystore.jks. If you have renamed the keystore, you must configure the keystore name in the Oracle Platform Security Services keystore service instance.
For information about configuring the keystore, see "Configuring Keystores for Message Protection".
Users and groups are maintained as part of the WebLogic Server security realm.
To migrate users and groups in embedded LDAP, you can migrate the data using either the Oracle WebLogic Administration Console or WLST. For a complete description of the steps required, see "Migrating Security Data" in Securing Oracle WebLogic Server.
To migrate users and groups in an LDAP store, there is no migration path. You need to recreate the users and groups and specify the assignments in the LDAP store in the new environment. See "Configuring Authentication Providers" in Securing Oracle WebLogic Server.
There are two types of credentials maintained in the credential store that you may need to migrate:
Username and password
Keystore and encryption key passwords
The migration steps are described in the sections below.
If users are stored in an embedded LDAP and migrated, as described in "Migrating Users and Groups", then you simply migrate the existing credentials to the new credential store. For a complete description of the steps required, see "Migrating Security Data" in Securing Oracle WebLogic Server.
If users are stored in an LDAP store, there is no automated migration path. You need to recreate the credentials in the credential store. For more information about configuring credentials, see "Adding Keys and User Credentials to the Credential Store".
If your Web service uses authorization policies, you must migrate the Oracle Platform Security Services application and system policies that grant permissions. For more information, see "Migrating with the Script migrateSecurityStore" in "Configuring the OPSS Security Store" in Oracle Fusion Middleware Application Security Guide.
There is no automated migration path for Oracle Platform Security Services configuration. You must recreate the configuration in the new environment.
There are three types of configurations in the Oracle Platform Security Services that you may need to recreate:
SAML trusted assertion issuer names (applicable for all SAML policies).
If you use the default configuration for SAML trusted issuer configuration, then no migration is required. For information about configuring SAML in the new environment, see "Configuring the SAML and Kerberos Login Modules".
Keystore locations and CSF key configuration for keystore and keystore password (applicable for message protection policies only).
If you use the default configuration for keystores, then no migration is required. For information about configuring keystores in the new environment, see "Configuring Keystores for Message Protection".
Keytab location and service principal name (applicable to Kerberos policy).
For information about configuring the keytab location and service principal name in the new environment, see "Configuring the SAML and Kerberos Login Modules".
There is no automated migration path for SSL configuration. You must configure SSL keystores and settings in the new environment. For more information about configuring SSL keystores and settings in the new environment, see "Configuring Keystores for SSL".
To migrate the Kerberos configuration:
Copy the Kerberos configuration file to the new environment, matching the directory structure. The Kerberos configuration file is located in the following locations, based on your operating system:
UNIX: /etc/krb5.conf
Windows: C:\windows\krb5.ini
Initialize the ticket cache with the correct credentials.
For more information, see "Using Kerberos Tokens".
You can export individual assertion templates from Oracle Enterprise Manager Fusion Middleware Control. You can then copy the policy to a directory or import the policy to move it to another repository.
For details about exporting and importing assertion templates, see the following sections:
To deploy an application in a new environment, you must export the application's deployment configuration to the new environment. Refer to the following topics for information about exporting WebLogic Java EE Web services, SOA composites, and ADF data control deployment configuration:
WebLogic Java EE Web services: "Exporting an Application for Deployment to New Environments"in Deploying Applications to Oracle WebLogic Server.
SOA composites: "Exporting a Running SOA Composite Application" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
ADF data controls: "WebCenter Configuration" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter .
Run-time Web service policy changes to ADF Business Control and WebCenter Web service applications are persisted in proprietary deployment descriptor (PDD) files. To preserve these policy changes in a scaled or new environment, or to propagate these changes in a domain, you must migrate the PDD files using WLST commands. The following procedure describes the steps required to migrate the PDD files.
Connect to the running instance of the WebLogic Administration Server in the domain in which the application is deployed. For instructions, see "Accessing the Web Services Custom WLST Commands".
Optionally, use the listWebServices(None,None,true)
command to list all the Web services in all applications and composites in the domain.
For example:
wls:/wls-domain/serverConfig> listWebServices(None,None,true)
/wls-domain/ManagedServer1/j2wbasicPolicy:
moduleName=j2wbasicPolicy, moduleType=web, serviceName=WssUsernameService
enableTestPage: true
enableWSDL: true
JRFWssUsernamePort http://host:port/j2wbasicPolicy/WssUsername
enable: true
enableREST: false
enableSOAP: true
maxRequestSize: -1
loggingLevel: NULL
security : oracle/wss_username_token_service_policy, enabled=true
enableWSDL: true
Attached policy or policies are valid; endpoint is secure.
.
.
.
Note: ThelistWebServices command output does not include details on SOA components, including policy attachments. |
Modify the policy configuration using Fusion Middleware Control or WLST. For example, to attach the policy oracle/wsmtom_policy policy to ManagedServer1 using WLST, enter the following command:
wls:/wls-domain/serverConfig> attachWebServicePolicy ('/wls-domain/ManagedServer1/j2wbasicPolicy','j2wbasicPolicy','web', 'WssUsernameService','JRFWssUsernamePort', 'oracle/wsmtom_policy,')
The policy change is persisted in the application PDD.
Restart the application.
Optionally, use the listWebServices(None,None,true)
command again to verify that the policy is attached to the server instance. For example:
wls:/wls-domain/serverConfig> listWebServices(None,None,true)
/wls-domain/ManagedServer1/j2wbasicPolicy :
moduleName=j2wbasicPolicy, moduleType=web, serviceName=WssUsernameService
enableTestPage: true
enableWSDL: true
JRFWssUsernamePort http://host:port/j2wbasicPolicy/WssUsername
enable: true
enableREST: false
enableSOAP: true
maxRequestSize: -1
loggingLevel: NULL
security : oracle/wss_username_token_service_policy , enabled=true
mtom : oracle/wsmtom_policy , enabled=true
Attached policy or policies are valid; endpoint is secure.
Export the application PDD to a JAR file using the exportJRFWSApplicationPDD
WLST command.
exportJRFWSApplicationPDD(application,pddJarFileName=None)
For example, to export the PDD for the j2wbasicPolicy application using the default JAR filename, use the following command:
wls:/wls-domain/serverConfig> exportJRFWSApplicationPDD('/wls-domain/ManagedServer1/j2wbasicPolicy', None)
The default name and path to the JAR file is displayed.
/tmp/j2wbasicPolicy-PDD-20100115-145338.jar
If you are scaling your environment, use the WebLogic Server Administration Console to clone a new Managed Server. For more information, see "Clone Servers" in the WebLogic Server Administration Server Online Help.
If you are migrating your application to a new environment, ensure that the policies and any other configuration artifacts are copied to the new environment. For more information, see "Migrating Policies" and "Migrating Policy Configuration".
In a scaled environment, start the cloned Managed Server.
Note that the oracle/wsmtom_policy is not attached to the cloned Managed Server. To do so using the listWebServices
command:
wls:/wls-domain/serverConfig> listWebServices(None,None,true)
.
.
.
/wls-domain/ClonedManagedServer/j2wbasicPolicy :
moduleName=j2wbasicPolicy, moduleType=web,serviceName=WssUsernameService
enableTestPage: true
enableWSDL: true
JRFWssUsernamePort http://host:port/j2wbasicPolicy/WssUsername
enable: true
enableREST: false
enableSOAP: true
maxRequestSize: -1
loggingLevel: NULL
security: oracle/wss_username_token_service_policy , enabled=true
Attached policy or policies are valid; endpoint is secure.
Import the application PDD to the new server, or to the new environment, using the importJRFWSApplicationPDD
command.
importJRFWSApplicationPDD(application,pddJarFileName)
For example, to import the PDD JAR created in step 6 to the cloned Managed Server, use the following command:
wls:/wls-domain/serverConfig> importJRFWSApplicationPDD ('/wls-domain/ClonedManagedServer/j2wbasicPolicy','/tmp/j2wbasicPolicy-PDD-20100115-145338.jar') application /wls-domain/ClonedManagedServer/j2wbasicPolicy PDD has been reset, please restart application now to uptake changes!
Restart the application and, optionally, verify the changes by executing the listWebServices(None,None,true)
command again. For example:
wls:/wls-domain/serverConfig> listWebServices(None,None,true)
.
.
.
/wls-domain/ClonedManagedServer/j2wbasicPolicy :
moduleName=j2wbasicPolicy, moduleType=web,serviceName=WssUsernameService
enableTestPage: true
enableWSDL: true
JRFWssUsernamePort http://host:port/j2wbasicPolicy/WssUsername
enable: true
enableREST: false
enableSOAP: true
maxRequestSize: -1
loggingLevel: NULL
security:oracle/wss_username_token_service_policy , enabled=true
mtom : oracle/wsmtom_policy , enabled=true
Attached policy or policies are valid; endpoint is secure.
Use the savePddToAllAppInstancesInDomain
command to apply the policy changes (that you applied to a single server in step 9 using the importJRFWSApplicationPDD
command) to all the server instances in the domain. This command is useful for propagating run-time policy changes to all servers in a cluster.
savePddToAllAppInstancesInDomain(applicationName,pddJarFileName,restartApp=true)
For example, to apply the same policy attachment to all server instances running the application in the domain, use the following command:
wls:/wls-domain/serverConfig> savePddToAllAppInstancesInDomain('j2wbasicPolicy','/tmp/j2wbasicPolicy-PDD-20100115-145338.jar',true)
The oracle/wsmtom_policy is now attached to all server instances in the domain and the application is automatically restarted.
Optionally, execute the listWebServices(None,None,true)
command to verify the changes were applied to all servers.
For more information about these deployment migration WLST commands and their arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.