This chapter describes how to install and configure the Oracle Communications IP Service Activator REST API web service.
To install the IP Service Activation REST API Web service:
Install the Oracle JDK and the Java environment.
When installing Oracle JDK and the Java environment, set the JAVA_HOME path and add JAVA_HOME/bin to PATH. See the IP Service Activator Installation Guide for more information about installing Java for IP Service Activator.
Install and configuring Oracle WebLogic Server.
See "Installing and Configuring Oracle WebLogic Server" for more information.
Create a WebLogic Server domain.
See Oracle WebLogic Server product documentation for more information about creating a WebLogic Server domain.
Create a JMS queue in Weblogic Server.
This JMS queue is the IPSA Web Service action queue.
Install IP Service Activator.
To use the REST API with IP Service Activator, you select the Web Service optional integration component when you run the Oracle Universal Installer. Alternatively, if you are running a silent installation, you use the Web Service response file to install IP Service Activator with REST API capability.
If the Web Service component was installed on a previous version of IP Service Activator, upgrade to the latest version and then redeploy the REST API web service.
For more information about installing IP Service Activator, see IP Service Activator Installation Guide.
Configure IP Service Activator REST API.
You configure the REST API in IP Service Activator's Configuration GUI. See "Configuring the REST API Web Service" for more information.
Deploy the REST API Web service to an Oracle WebLogic Server application server.
You deploy the REST API from the IP Service Activator's Configuration GUI. See "Deploying and Undeploying Web Services" for more information.
You can install Web services on the same server with other IP Service Activator components, or you can install Web services as a standalone component.
When installing Oracle WebLogic Server for the REST API, consider the following:
Install Oracle WebLogic Server (12.2.1.2 or later). Use the fmw_12.2.x.y.z_infrastructure.jar as the installer.
Create database schemas using the Repository Creation Utility (RCU), which is included in the WebLogic Server installation. The schemas are required for creating the WebLogic Server domain. Each schema can be used by only one domain. If you create a new domain, you must also create a new schema. Use unique schema names. For complete information about using RCU, see Oracle Fusion Middleware Creating Schemas with the Repository Creation Utility at the Oracle Help Center:
When creating the domain, select JRF.
For more information about installing WebLogic Server, see Fusion Middleware Installing and Configuring Oracle WebLogic Server and Coherence at the Oracle Help Center:
To use a REST API Web service, you must set up Secure Sockets Layer (SSL) in WebLogic Server to ensure that all connections are secure and encrypted.
To configure the WebLogic Server to use SSL, you must have an SSL certificate for the server that is running WebLogic Server. Production servers should have a trusted certificate. Lab and testing servers can use self-signed certificates. Use Java to generate custom keystore files and then configure WebLogic Server to use those files.
To configure the WebLogic Server to use custom identity and trust keystore files:
Generate custom SSL identity and trust files by entering the following in the Java utility:
keytool -genkey -alias mykey -keyalg RSA -keysize 1024 -sigalg SHA256withRSA -validity 128 -keypass 123456 -keystore identity.jks -storepass 123456 keytool -export -alias mykey -file root.cer -keystore identity.jks -storepass 123456 keytool -import -alias mykey -file root.cer -keystore trust.jks -storepass 123456
where mykey is the key name, and 123456 is the key password.
The system generates the following two files:
identity.jks
trust.jks
Copy the .jks files to the security directory of the WebLogic Server, for example, OracleHome/user_projects/domains/domain_name/security.
Log in to the WebLogic Server.
The WebLogic Administration Console is displayed.
In the left pane, expand Environment, and select Servers.
Select the server where you want to configure the identity and trust keystores.
Select Configuration, and then select Keystores.
Select the Custom Identity and Custom Trust option, and specify the identity.jks and trust.jks files that you generated in step 1.
Note:
The key name must match the key password that you entered when you generated the files.Click the SSL tab to define the SSL configuration options for the private key alias and password.
For more information about setting up WebLogic Server security, see Fusion Middleware Administering Security for Oracle WebLogic Server at the Oracle Help Center:
You can test whether SSL is set up correctly in the WebLogic Server.
To test the SSL configuration:
In a browser, go to the WebLogic Administration Console, for example, enter:
http://hostname:7001/console
If SSL is configured correctly, the browser connects to the WebLogic Administration Console using a secure connection and the URL changes from http:// to https://, for example:
https://hostname:7002/console
The default port number for SSL is 7002 and if your browser connects, SSL is configured correctly.
Note:
If you are using a self-signed certificate for authentication, the browser might need to import the certificate before you make the connection.The REST API Web service supports only secure connections with authentication.
When you deploy the REST web service, the system creates and configures a WebLogic group called IpsaDomainController. The REST web service user, which is called ipsa_ws_user by default, is configured in the Web Service/Common section of the IP Service Activator Configuration graphical user interface (GUI). This web service user is automatically added to the IpsaDomainController group. See "Deploying and Undeploying Web Services" for information about deploying the Web service for use with the REST API.
The REST Web service is configured to accept calls only from a user that belongs to the IpsaDomainController group, as authenticated by WebLogic Server, or is a specific user with the name IpsaDomainController.
You can configure additional users and add them to this group using the WebLogic Server Administration Console.
For more information about setting up WebLogic Server security, see Fusion Middleware Administering Security for Oracle WebLogic Server at the Oracle Help Center:
You use the IP Service Activator Configuration GUI to configure the REST API Web service and deployment parameters.
Note:
The database and CORBA components must also be configured for the Web service to function correctly. See IP Service Activator System Administrator's Guide for information about configuring other components using the Configuration GUI.To configure the REST API web service:
Open the IP Service Activator Configuration GUI.
If you installed the Web Services component during IP Service Activator installation, the IP Service Activator Configuration GUI displays the Web Service folder in the tree view.
See IP Service Activator System Administrator's Guide for more information.
In the Configuration GUI tree view, double-click the Web Service folder.
Click Common.
Enter the configuration parameters.
For information about Web service parameters, see IP Service Activator Installation Guide, Post-Installation Tasks.
Note:
If you change IP Service Activator Web service parameters, re-deploy the Web service to ensure that the changes take effect. See "Deploying and Undeploying Web Services" for more information.Table 2-1 describes the Web service configuration parameters.
Table 2-1 Web Service Configuration Parameters
| Parameter | Description |
|---|---|
|
IPSA ORB Initial Host |
The host machine for IPSA CORBA. Default is 127.0.0.1. |
|
IPSA ORB Initial Port |
The host port for IPSA CORBA. Default is 2809. |
|
Database Server IP Address |
Database server IP address. |
|
Database Server Port |
The database server port. Default is 1521. |
|
Database Service Name |
The database service name. Default is IPSA.WORLD. |
|
Database User Id |
The database user ID. Default is admin. |
|
Database User Password |
The database user password. |
|
Confirm Database User Password |
Re-enter the database user password. |
|
IPSA User Name |
The IP Service Activator user name. Default is admin. |
|
IPSA User password |
The IP Service Activator web service user password. |
|
Confirm IPSA User password |
Re-enter the IP Service Activator web service user password. |
|
IPSA Web Service User Name |
The IP Service Activator web service user name. Default is ipsa_ws_user. |
|
IPSA Web Service User password |
The IP Service Activator web service user password. |
|
IPSA Web Service JMS Queue JNDI |
The JMS queue JNDI for the REST API action queue. The default value is: jms/IPSAJMSQueue |
|
IPSA Web Service JMS connection factory JNDI |
The JMS Connection factory JNDI for the REST API action queue. The default value is: jms/IPSAConnectionFactory |
|
Maximum Query Load |
The maximum query load in bytes. Default is 1024000. |
|
EOM Debug Level |
Select an option to define the IP Service Activator EOM Debug level. OFF: logging is disabled ERROR: unexpected exceptions are logged at this level (default) TRACE: all logging is enabled. OIM commands and responses are logged at this level. DEBUG: lower logging level than Trace INFO: informational logging. Lower logging level than Debug. |
|
Maximum Retry on Connection Failure |
The maximum number of retries on recoverable conditions, for example, database/OIM failures. Default is 3. |
|
OIM Session Timeout |
OSS Integration Manager session timeout in seconds. Default is 1200. |
|
OJDL Transaction Short Watch Interval |
The OJDL transaction short watch interval in seconds. Default is 5. Also, you can use this value to configure transaction and discovery monitoring. |
|
OJDL Transaction Short Watch Period |
The OJDL transaction short watch period in seconds. Default is 300. Also, you can use this value to configure transaction and discovery monitoring. |
|
OJDL Transaction Long Watch Interval |
The OJDL transaction long watch interval in seconds. Default is 60. Also, you can use this value to configure transaction and discovery monitoring. |
|
OJDL Transaction Long Watch Period |
The OJDL transaction long watch period in seconds. Default is 3600. Also, you can use this value to configure transaction and discovery monitoring. |
|
OJDL Transaction Commit Period |
The OJDL transaction commit period in seconds. Default is 60. Also, you can use this value to configure transaction and discovery monitoring. This value is used as the time out value for a transaction commit or for device discovery completion. The REST API posts Timedout to the JMS action queue if the time exceeds this value. |
If you have an OSS Integration Manager (OIM), or multiple OIMs on multiple servers, that you previously installed and configured in IP Service Activator, you can configure the parameters to enable the Web service to interact with those OIMs.
Note:
IP Service Activator does not support multiple OIMs on a single server.Using the OIM Configuration component in IP Service Activator Configuration GUI, you can add, delete, and modify the OIM configurations that are used for Web services.
For more information about installing and configuring OIMs in IP Service Activator, see IP Service Activator OSS Integration Manager Guide.
To configure OIM for Web services:
In the Configuration GUI tree view, double-click the Web Service folder.
Click OIM Configuration.
Enter the configuration parameters for the OIM that you want to configure.
For information about OIM configuration parameters, see Table 2-2.
Table 2-2 OIM Configuration Parameters
| Parameter | Description |
|---|---|
|
Name |
The CORBA name of the integration manager. |
|
Maximum Sessions |
The maximum number of OIM sessions. Default is 10. |
|
Minimum Idle Sessions |
The minimum number of idle sessions. Default is 5. |
|
Read Only |
Select this option if you want to use the integration manager for read only. Deselect this option if you want to use it for both reading and writing. |
You use the IP Service Activator Configuration GUI to deploy the REST API Web service and deployment parameters. Deploy the REST API Web service after you configure all parameters, including the deployment parameters, in the IP Service Activator Configuration GUI. For information about Web service parameters, see "Configuring the REST API Web Service". For information about OIM configuration parameters, see "Configuring OSS Integration Manager".
You can also undeploy the Web service.
Note:
To configure the Web service deployment, you require information about the WebLogic Server on which the Order and Service Management (OSM) server is deployed. WebLogic Server parameters are required to connect to a Oracle WebLogic Server.See "Installing and Configuring Oracle WebLogic Server" for information about WebLogic Server. See Order and Service Management Concepts and Order and Service Management Installation Guide for information about OSM.
To deploy the Web service:
In the Configuration GUI tree view, double-click the Web Service folder.
Click Deployment.
Enter the configuration parameters for the Web service deployment.
Click Deploy.
The configuration tool does the following:
Updates the IpsaWebService.ear file with the parameter values that you entered in the web service node.
Creates a JMS Server, a JMS Module, and JMS queues in WebLogic, if they are not already created.
Creates a web service security user group and a user in WebLogic, if they are not already created.
Deploys the IpsaWebService.ear file to WebLogic.
For information about web service deployment parameters, see Table 2-3.
Table 2-3 Web Service Deployment Parameters
| Parameter | Description |
|---|---|
|
Weblogic Host |
The WebLogic host. Default is 127.0.0.1. |
|
Weblogic Port |
The port number for the WebLogic server. Default is 7001. |
|
Weblogic Admin User Name |
The WebLogic administrator user name. Default is weblogic. |
|
Weblogic Admin User Password |
The WebLogic administrator user password. |
|
Confirm Weblogic Admin User Password |
Re-enter the WebLogic administrator user password. |
|
Weblogic Secure Connection |
Select this option if you want to use a secure connection to the WebLogic server. Check box is selected by default. |
|
Weblogic Target Server |
The WebLogic target server where you want to deploy the IP Service Activator web service. |
|
Weblogic Home |
The directory where WebLogic is installed on the server. |
To undeploy the web service:
In the Configuration GUI tree view, double-click the Web Service folder.
Click Deployment.
Click Undeploy.
IP Service Activator access control security for Web services determines the functionality to which each user has access. To set up access control security, create a security role. Give this role the privilege to start IP Service Activator Web services. When the Web service client accesses the Web service, the client needs to authenticate itself to the Oracle WebLogic Server hosting IP Service Activator Web service. See Oracle WebLogic Administration Guide for information about setting up access security.
Note:
Oracle WebLogic access control security protects only WebLogic Server resources and does not cover secure communication with IP Service Activator Web services. As a result, SOAP messages transmitted between the Web service and its clients are in plain text.The REST API Web service allows only access-level security. Clients must use a user ID that is a member of the IPSA_WS_USERS_GROUP group to communicate with IP Service Activator Web services. The web.xml file defines the security role IPSA_WS_USERS and the weblogic.xml file defines the security principal name as IPSA_WS_USERS_GROUP.
Running the installer creates a default user. For information about the default user names and passwords used with Web services, see IP Service Activator Installation Guide. This user is a member of the IPSA_WS_USERS_GROUP group. Due to limitations of the WebLogic Server console, information created by the command line tools, such as the role name, might not be available on the console.