# SDK User Guide

# Installing and Configuring the SDK

This chapter describes setting up the Oracle Communications Services Gatekeeper SDK for use. The chapter includes information on:

- Installation procedure
- Setting up WS-Policy

## Installation procedure

To install the Oracle Communications Services Gatekeeper SDK:

Note: | The sample domain that is provided with the Oracle Communications Services Gatekeeper SDK can be used directly. Separate domain configuration is unnecessary.

### Launch the GUI Installer - Windows

If you are using the GUI-based installer on a Windows machine, do the following:

1. Log in to the Windows system.
2. Go to the directory where you have copied the installation program. You acquire this program either from a Oracle Communications Services Gatekeeper SDK CD or the Download Center.
3. If you are using Explorer to find the file, double-click the installation file, `ocsg_sdk410_win32.exe`
4. If you are using the console window to find the file, enter the following command:

    ocsg_sdk410_win32

Note: | You can also include the `-log=full_path_to_log_file` option in the command line to create a verbose installation log. For example:

    ocsg_sdk410_win32 -log=<full_path>install.log

5. Go on to Respond to the Prompts

### Launch the GUI Installer - UNIX/Linux

If you are using the GUI-based installer on a UNIX/Linux machine, do the following:

1. Log into the target UNIX system
2. Go to the directory where you have copied the installation program. You acquire this program either from the Oracle Communications Services Gatekeeper SDK CD or the Download Center.
3. Launch the installation by entering the following commands:

`chmod a+x ocsg_sdk410_<appropriate-platform-filename>.bin`

`./ocsg_sdk410_<appropriate-platform-filename>.bin`

Note: | You can also include the `-log=full_path_to_log_file` option in the command line to create a verbose installation log. For example:

    ocsg_sdk410_<appropriate-platform-filename>.bin -log=<full_path>install.log

4. Go on to Respond to the Prompts

### Respond to the Prompts

The installation program prompts you to enter specific information about your system and configuration. For instructions on responding to the prompts during installation, see the following table.

In this window... | Perform the following action...
--- | ---
Welcome | Click Next to proceed with the installation. You may cancel the installation at any time by clicking Exit.
Choose BEA Home Directory | Specify the BEA Home directory that will serve as the central support directory for the installed on the target system. If you already have a BEA Home directory on your system, you can select that directory (recommended) or create a new BEA Home directory.
Note: | If you also have Oracle Communications Services Gatekeeper installed on this machine, you will need to select a new BEA home. A separate version of WebLogic Server will be installed just for the SDK.
If you choose to create a new directory by typing a new directory name in the BEA Home Directory field, the installation program automatically creates one for you. You can also click Browse and select a directory from the BEA Home Directory Selection window.
Choose Products and Components | Make sure Oracle Communications Services Gatekeeper SDK is selected. Click Next.
Choose JDK | Select the JDK to use. Click Next.
Choose Product Installation Directory | Specify the directory in which you want to install the Oracle Communications Services Gatekeeper software. This is the directory from which information will be copied during the domain configuration phase. Once you have chosen your directory, click Next. You can accept the default product directory (ocsg_4.1) or create a new product directory.
Install Windows Service | Do not install Node Manager Service. Click Next.
Choose Shortcut Location This window is displayed only under the following conditions: You have Administrator privileges. You are performing an initial installation. You are installing on a Windows platform. | Specify the Start menu folder in which you want the Start menu shortcuts created. You can select from the following options: All Users Start menu folder Selecting this option provides all users registered on the machine with access to the installed software. However, only users with Administrator privileges can create shortcuts in the All Users folder. Therefore, if a user without Administrator privileges uses the Configuration Wizard to create domains, Start menu shortcuts to the domains are not created. In this case, users can manually create shortcuts in their local Start menu folders, if desired. Press ALT+Y on the keyboard to select the All Users Start Menu. Local user's Start menu folder Selecting this option ensures that other users registered on this machine will not have access to the Start menu entries for this installation. Press ALT+N on the keyboard to select the Local User's start menu.
Status | Read the information displayed about Oracle products and services. When the installation program has finished copying the specified files to your system, click Next.
Installation Complete | Specify whether you want to run the QuickStart application. QuickStart, designed to assist first-time users in evaluating, learning, and using the software, provides quick access to domain configuration wizard. Clear the check box for this option if you do not want to launch QuickStart. Unless you want to make changes to the standard sample domain, a separate domain configuration is not necessary.

## Setting up WS-Policy

One of the first things you must do in setting up Oracle Communications Services Gatekeeper SDK is to establish Web Services security. Web Services security controls Oracle Communications Services Gatekeeper Simulator’s interactions with Application Service Providers

### Web Services Security

Web Services Security provides end-to-end message-level security for web services through an implementation of the WS-Security standard. WS-Security defines a mechanism for adding three levels of security to SOAP messages:

- Authentication tokens. WS-Security authentication tokens lets an application provide a user name and password or X509 certificate for the purpose of authentication headers.
- XML encryption. WS-Security’s use of W3C’s XML encryption standard enables the XML body or portion of it to be encrypted to ensure message confidentiality.
- XML digital signatures. WS-Security’s use of W3C's XML digital signatures lets the message be digitally signed to ensure message integrity. The signature is based on the content of the message itself (by applying a hash function and public key), so if the message is altered en route, the signature becomes invalid.

Oracle Communications Services Gatekeeper uses WebLogic Server mechanisms for Web Services security- see:

- Oracle WebLogic Server Securing WebLogic Web Services at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/webserv_sec/
- Oracle WebLogic Server Understanding WebLogic Security at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/secintro/
- Web Services Security specifications at http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss

Message level security for SOAP messages is achieved by applying WS-Security and WS-Security policy standards. Authentication is handled transparently by WS-Security and subsequently by the configured authentication providers and login modules of the WebLogic Security framework. WS-Security also supports signing and encrypting a message by providing a security token hierarchy associated with the keys used for signing and encryption (for message integrity and confidentiality).

The following steps outline the general WebLogic security configurations that have to be performed, either automatically using a script or manually from the Administration Console.

- Configure Policies for WS-Security as described below.
- If using SAML tokens, configure WebLogic SAML Identity Assertion Provider which authenticates users based on SAML assertions and SAML credential mapping provider. A SAML Identity Assertion Provider is required only if you are using SAML assertions.

### Configuration Workflow: Policies for WS-Security

This section outlines how to apply an existing WS-Policy and where to find more information about creating and using custom WS-Policies.

#### Apply a WS-Policy to a Web Service: Quick start

This section outlines how to apply a WSSE policy to a Web Service endpoint in the Oracle Communications Services Gatekeeper Simulator.

Standard WebLogic Server mechanisms are used. See Oracle WebLogic Server Management Console On-line Help at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/ConsoleHelp/pagehelp/J2EEwebservicewebservicepolicytitle.html for a full description on how to configure a policy file for a Web Service.

The Oracle Communications Services Gatekeeper Simulator must be started, see Start the Oracle Communications Services Gatekeeper Simulator.

Starting in WebLogic Console:

1. In the Domain Structure pane, select Deployments.
2. In Summary of Deployments page, expand simulator.
3. Click on a Web Service to apply Web Services security to, for example SendSmsService. All Web Services are named according to the interface they implement.

This shows the page Settings for <Web Service>

4. Click the Configuration tab.
5. Click WS-Policy sub-tab.
6. Click Service endpoint <Web Service>.
7. Choose which security policy to apply for the endpoint:

1. Select the appropriate WS-Policy file in Available Endpoint Policies, see Available default WS-Policies.
2. Move it to the list in Chosen Endpoint Policies by clicking on the arrow button.
3. When the WS-Policy files have been chosen, click OK.

8. In the Save Deployment Plan Assistant you choose where to store the deployment plan.
9. Apply the changes.

Note: | Applying a security policy to a Web Service establishes, by default, both inbound and outbound security policies. Because there is no way for Oracle Communications Services Gatekeeper Simulator to know what security policies may be required by a client to which it is returning a notification, outbound security must be turned off. If you wish to secure the link by which Oracle Communications Services Gatekeeper Simulator returns notifications, you should use SSL.

Note: | To turn off outbound security associated with a particular WS-Policy file, you must edit the plan.xml file that is created when you attach Policy to a Web Service, as in step 8 above. Make sure the <value> element is set to `inbound` as in the following stanza:

Listing 4-1 Plan.xml snippet to be edited

    <variable>

          <name>WsPolicy_policy:Auth.xml_Direction_11745107731400</name>

          <value>inbound</value>

    </variable>

### Create and Use a Custom WS-Policy

See Oracle WebLogic Server Securing WebLogic Web Services at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/webserv_sec/ for information on how to create and use a custom WS-Policy file.

Also see Oracle WebLogic Server Management Console On-line Help at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/ConsoleHelp/pagehelp/J2EEwebservicewebservicepolicytitle.html for a full description on how to configure a policy file for a Web Service

#### Available default WS-Policies

WS-Policy files can be used to require applications clients to authenticate, digitally encrypt, or digitally sign SOAP messages. Out-of-the-box Oracle Communications Services Gatekeeper supplies files to do those three things, respectively: auth.xml, encrypt.xml, and sign.xml. If the built-in WS-Policy files do not meet your security needs, you can build custom policies.

WS-Policy assertions are used to specify a Web Services’ requirements for digital signatures and encryption, along with the security algorithms and authentication mechanisms that it requires, for example Policy for SAML.