# Application Development Guide

# Interacting with Oracle Communications Services Gatekeeper

In order to interact with Oracle Communications Services Gatekeeper, applications use either SOAP-based, RESTful, or native interfaces. Those applications using SOAP-based interfaces must manipulate the SOAP messages that they use to make requests in certain specialized ways.They must add specific information to the SOAP header, and, if they are using for example Multimedia Messaging, they must send their message payload as a SOAP attachment. Applications using the native interfaces use the normal native interface mechanisms, which are not covered in this document.

The following chapter presents a high-level description of the SOAP mechanisms and how they function to manage the interaction between Oracle Communications Services Gatekeeper and the application. It covers:

- Requirements for Using the SOAP-based Facades

- Authentication
- Session Management
- Service Correlation
- Parameter Tunneling
- SOAP attachments

The mechanisms for dealing with these requirements programmatically depend on the environment in which the application is being developed.

Note: | Clients created using Axis 1.2 or older will not work with some communication services. Developers should use Axis 1.4 or newer if they wish to use Axis.

For examples using the Oracle WebLogic Server environment to accomplish these sorts of tasks, see:

- Managing SOAP headers and SOAP attachments programmatically

## Requirements for Using the SOAP-based Facades

If your application is using the a SOAP-based facade (set of interfaces) to interact with Oracle Communications Services Gatekeeper, there are four types of elements you may need to add to your application’s SOAP messages to Oracle Communications Services Gatekeeper.

### Authentication

In order to secure Oracle Communications Services Gatekeeper and the telecom networks to which it provides access, applications are usually required to provide authentication information in every SOAP request which the application submits. Oracle Communications Services Gatekeeper leverages the WebLogic Server Web Services Security framework to process this information.

Note: | WS Security provides three separate modes of providing security between a Web Service client application and the Web Service itself for message level security - Authentication, Digital Signatures, and Encryption. For an overview of WebLogic Server 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 Communications Services Gatekeeper supports three authentication types:

- Username Token
- X.509 Certificate Token
- SAML Token

The type of token that the particular Oracle Communications Services Gatekeeper operator requires is indicated in the Policy section of the WSDL files that the operator makes available for each application-facing interface it supports. In the following WSDL fragment, for example, the required form of authentication, indicated by the `<wssp:Identity>` element, is Username Token.

Listing 3-1 WSDL fragment showing Policy

    <s0:Policy s1:Id="Auth.xml">
    	<wssp:Identity>
    	<wssp:SupportedTokens>
    		<wssp:SecurityToken TokenType="http://docs.oasisopen.org/wss/2004/01/oasis200401wssusernametokenprofile1.0#UsernameToken">
    		<wssp:UsePassword Type="http://docs.oasisopen.org/wss/2004/01/oasis200401wssusernametokenprofile1.0#PasswordText"/>
    		</wssp:SecurityToken>
    		<wssp:SecurityToken TokenType="http://docs.oasisopen.org/wss/2004/01/oasis200401wssx509tokenprofile1.0#X509v3"/>
    	</wssp:SupportedTokens>
    	</wssp:Identity>
    </s0:Policy>
    <wsp:UsingPolicy n1:Required="true"/>

Note: | If the WSDL also has a `<wssp: Integrity>` element, digital signing is required (WebLogic Server provides WS-Policy: sign.xml). If it has a `<wssp:Confidentiality>` element, encryption is required (WebLogic Server provides WS-Policy: encrypt.xml).

#### SOAP Header Element for Authentication

Below are examples of the three types of authentication that can be used with Oracle Communications Services Gatekeeper.

##### Username Token

In the Username Token mechanism, which is specified by the use of the `<wsse:UsernameToken>` element in the header, authentication is based on a username, specified in the `<wsse:Username>` element and a password, specified in the `<wsse:Password>` element.

Two types of passwords are possible, indicated by the Type attribute in the Password element:

- `PasswordText` indicates the password is in clear text format.
- `PasswordDigest` indicates that the sent value is a Base64 encoded, SHA-1 hash of the UTF8 encoded password.

There are two more optional elements in Username Token, introduced to provide a countermeasure for replay attacks:

- `<wsse:Nonce>`, a random value that the application creates.
- `<wsu:Created>`, a timestamp.

If either or both `the Nonce` and `Created` elements are present, the Password Digest is computed as: Password_Digest = Base64(SHA-1(nonce+created+password))

When the application sends a SOAP message using Username Token, the WSEE implementation in Oracle Communications Services Gatekeeper evaluates the username using the associated authentication provider. The authentication provider connects to the Oracle Communications Services Gatekeeper database and authenticates the username and the password. In the database, passwords are stored as MD5 hashed representations of the actual password.

Listing 3-2 Example of a WSSE: Username Token SOAP header element

    <wsse:UsernameToken wsu:Id="Example-1">

      <wsse:Username> myUsername </wsse:Username>

      <wsse:Password Type="PasswordText">myPassword</wsse:Password>

      <wsse:Nonce EncodingType="..."> ... </wsse:Nonce>

      <wsu:Created> ... </wsu:Created>

    </wsse:UsernameToken>

The UserName is equivalent to the application instance ID. The Password part is the password associated with this UserName when the application credentials was provisioned in Oracle Communications Services Gatekeeper.

For more information on Username Token, see http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf

##### X.509 Certificate Token

In the X.509 Token mechanism, the application’s identity is authenticated by the use of an X.509 digital certificate.

Typically a certificate binds the certificate holder’s public key with a set of attributes linked to the holder’s real world identity – for example the individual’s name, organization and so on. The certificate also contains a validity period in the form of two date and time fields, specifying the beginning and end of the interval during which the certificate is recognized.

The entire certificate is (digitally) signed with the key of the issuing authority. Verifying this signature guarantees

- that the certificate was indeed issued by the authority in question
- that the contents of the certificate have not been forged, or tampered with in any way since it was issued

For more information on X.509 Token, see http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf

The default identity assertion provider in Oracle Communications Services Gatekeeper verifies the authenticity of X.509 tokens and maps them to valid Oracle Communications Services Gatekeeper users.

Note: | While it is possible to use the out-of-the-box keystore configuration in Oracle Communications Services Gatekeeper for testing purposes, these should not be used for production systems. The digital certificates in these out-of-the-box keystores are only signed by a demonstration certificate authority For information on configuring keystores for production systems, see the section about configuring identity and trust in Oracle WebLogic Server Securing WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/secmanage/.

The x.509 certificate common name (CN) for an application must be the same as the account UserName, which is the string that was referred to as the `applicationInstanceGroupId` in previous versions of Oracle Communications Services Gatekeeper. This is provided by the operator when the account is provisioned.

Listing 3-3 Example of a WSSE: X.509 Certificate SOAP header element

    <wsse:Security xmlns:wsse="..." xmlns:wsu="...">

      <wsse:BinarySecurityToken wsu:Id="binarytoken"

        ValueType="wsse:X509v3"

        EncodingType="wsse:Base64Binary">

          MIIEZzCCA9CgAwIBAgIQEmtJZc0…

      </wsse:BinarySecurityToken>

      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

      <ds:SignedInfo>

        <ds:Reference URI="#body">…</ds:Reference>

        <ds:Reference URI="#binarytoken">…</ds:Reference>

      </ds:SignedInfo>

      <ds:SignatureValue>HFLP…</ds:SignatureValue>

        <ds:KeyInfo>

          <wsse:SecurityTokenReference>

            <wsse:Reference URI="#binarytoken" />

          </wsse:SecurityTokenReference>

        </ds:KeyInfo>

      </ds:Signature>

    </wsse:Security>

##### SAML Token

Oracle Communications Services Gatekeeper, using WebLogic Server’s WSSE implementation, supports SAML versions 1.0 and 1.1. The versions are similar. See
http://www.oasis-open.org/committees/download.php/3412/sstc-saml-diff-1.1-draft-01.pdf for an overview of the differences between the versions.

In SAML, a third party, the Asserting Party, provides the identity information for a Subject that wishes to access the services of a Relying Party. This information is carried in an Assertion. In the SAML Token type of Authentication, the Assertion (or a reference to an Assertion) is provided inside the `<WSSE:Security>` header in the SOAP message. The Relying Party (which in this case is Oracle Communications Services Gatekeeper, using the WebLogic Security framework) then evaluates the trustworthiness of the assertion, using one of two confirmation methods.

- Holder-of-Key
- Sender-Voucher

For more information on these confirmation methods, see the sections about SAML Token Profile in Oracle Weblogic Server Understanding WebLogic Security at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/secintro/.

Listing 3-4 Example of a WSSE: SAML Token SOAP header element

    <wsse:Security>

    <saml:Assertion MajorVersion="1" MinorVersion="0"

        AssertionID="186CB370-5C81-4716-8F65-F0B4FC4B4A0B"

        Issuer="www.test.com" IssueInstant="2001-05-31T13:20:00-05:00">

      <saml:Conditions NotBefore="2001-05-31T13:20:00-05:00"

        NotAfter="2001-05-31T13:25:00-05:00"/>

      <saml:AuthenticationStatement AuthenticationMethod="password"

        AuthenticationInstant="2001-05-31T13:21:00-05:00">

        <saml:Subject>

          <saml:NameIdentifier>

            <SecurityDomain>"www.bea.com"</SecurityDomain>

            <Name>"cn=localhost,co=bea,ou=sales"</Name>

          </saml:NameIdentifier>

        </saml:Subject>

      </saml:AuthenticationStatement>

    </saml:Assertion>

    ...

    </wsse:Security>

### Session Management

Oracle Communications Services Gatekeeper can be configured to run in session mode or sessionless mode. In session mode, an application must establish a session using the Session Manager Web Service before it is allowed to run traffic through Oracle Communications Services Gatekeeper. The session allows Oracle Communications Services Gatekeeper to keep track of all of the traffic sent by a particular application for the duration of the session, which lasts until the session times out, based on an operator-set interval, or until the application closes the session. The session is good for an entire Oracle Communications Services Gatekeeper domain, across clusters, and covers all communication services to which the application has contractual access.

In sessionless mode, the application is not required to establish a session.

#### Session Mode

An application establishes a session in Oracle Communications Services Gatekeeper by invoking the `getSession()` operation on the Session Manager Web Service. This is the only request that does not require a SessionID. In the response to this operation, a string representing the Session ID is returned to the client, and an Oracle Communications Services Gatekeeper session, identified by the ID, is established. The session is valid until either the session is terminated by the application or an operator-established time period has elapsed. The SessionID must appear in the `wlng:Session` element in the header of every subsequent SOAP request.

Listing 3-5 Example of a SessionID SOAP header element

    <Session>

      <SessionId>app:-2810834922008400383</SessionId>

    </Session>

#### Sessionless Mode

It is also possible to run Oracle Communications Services Gatekeeper without using the session mechanism. In this case the application simply uses whichever WS-Security mechanism is required by the Oracle Communications Services Gatekeeper operator.

### Service Correlation

In some cases the service that an application provides to its end-users may involve accessing multiple Oracle Communications Services Gatekeeper communication services. For example, a mobile user might send an SMS to an application asking for the pizza place nearest to his current location. The application then makes a Terminal Location request to find the user’s current location, looks up the address of the closest pizza place, and then sends the user an MMS with all the appropriate information. Three Oracle Communications Services Gatekeeper communication services are involved in executing what for the application is a single service. In order to be able to correlate the three communication service requests, Oracle Communications Services Gatekeeper uses a Service Correlation ID, or SCID. This is a string that is captured in all the CDRs and EDRs generated by Oracle Communications Services Gatekeeper. The CDRs and EDRs can then be orchestrated in order to provide special treatment for a given chain of service invocations, by, for example, applying charging to the chain as a whole rather than to the individual invocations.

The SCID is not provided by Oracle Communications Services Gatekeeper. When the chain of services is initiated by an application-initiated request, the application must provide, and ensure the uniqueness of, the SCID within the chain of service invocations.

Note: | In certain circumstances, it is also possible for a custom service correlation service to supply the SCID, in which case it is the custom service’s responsibility to ensure the uniqueness of the SCID.

When the chain of services is initiated by a network-triggered request, Oracle Communications Services Gatekeeper calls an external interface to get the SCID. This interface must be implemented by an external system. No utility or integration is provided out-of-the box; this must be a part of a system integration project. It is the responsibility of the external system to provide, and ensure the uniqueness of, the SCID.

The SCID is passed between Oracle Communications Services Gatekeeper and the application through an additional SOAP header element, the SCID element. Because not every application requires the service correlation facility, this is an optional element.

Listing 3-6 Example of a SCID SOAP header element

    <scid>myId</scid>

### Parameter Tunneling

Parameter tunneling is a feature that allows an application to send additional parameters to Oracle Communications Services Gatekeeper and lets a plug-in use these parameters. This feature makes it possible for an application to tunnel parameters that are not defined in the application-facing interface and can be seen as an extension to the it.

The application sends the tunneled parameters in the SOAP header of a Web Services request.

The parameters are defined using key-value pairs encapsulated by the tag <xparams>. The xparams tag can include one or more <param> tags. Each <param> tag has a key attribute that identifies the parameter and a value attribute that defines the value of the parameter. In the example below, the application tunnels the parameter `aParameterName` and assigns it the value `aParameterValue`.

Listing 3-7 SOAP header with a tunneled parameter.

    <soapenv:Header>

    ...

      <xparams>

        <param key="aParameterName" value="aParameterValue" />

      </xparams>

    ...

    </soapenv:Header>

Depending on the plug-in the request reaches, the parameter is fetched and used in the request towards the network node.

### SOAP attachments

In some communication services, the request payload are sent as SOAP attachments. Listing 3-8 below shows a Multimedia Messaging `sendMessage` operation that contains an attachment carrying a jpeg image.

Listing 3-8 Example of a SOAP message with attachment (full content is not shown)

    POST /parlayx21/multimedia_messaging/SendMessage HTTP/1.1

    Content-Type: multipart/related; type="text/xml"; start="<1A07DC767BC3E4791AF25A04F17179EE>"; 	boundary="----=_Part_0_2633821.1170785251635"

    Accept: application/soap+xml, application/dime, multipart/related, text/*

    User-Agent: Axis/1.4

    Host: localhost:8000

    Cache-Control: no-cache

    Pragma: no-cache

    SOAPAction: ""

    Content-Length: 4652

    Connection: close

    ------=_Part_0_2633821.1170785251635

    Content-Type: text/xml; charset=UTF-8

    Content-Transfer-Encoding: binary

    Content-Id: <1A07DC767BC3E4791AF25A04F17179EE>

      <?xml version="1.0" encoding="UTF-8"?>

        <soapenv:Envelope       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

          xmlns:xsd="http://www.w3.org/2001/XMLSchema"

          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

          <soapenv:Header>

            <ns1:Security ns1:Username="app:-4206293882665579772"

              ns1:Password="app:-4206293882665579772"

              soapenv:actor="wsse:PasswordToken"

              soapenv:mustUnderstand="1"           xmlns:ns1="/parlayx21/multimedia_messaging/SendMessage">

            </ns1:Security>

          </soapenv:Header>

          <soapenv:Body>

            <sendMessage xmlns=

              "http://www.csapi.org/schema/parlayx/multimedia_messaging/send/v2_4/local">

              <addresses>tel:234</addresses>

              <senderAddress>tel:567</senderAddress>

              <subject>Default Subject Text</subject>

              <priority>Normal</priority>

              <charging>

                <description xmlns="">Default</description>

                <currency xmlns="">USD</currency>

                <amount xmlns="">1.99</amount>

                <code xmlns="">Example_Contract_Code_1234</code>

              </charging>

            </sendMessage>

          </soapenv:Body>

        </soapenv:Envelope>

    ------=_Part_0_2633821.1170785251635

    Content-Type: image/jpeg

    Content-Transfer-Encoding: binary

    Content-Id:

      <9FFD47E472683C870ADE632711438CC3>???? JFIF      ?? C#%$""!&+7/&)4)!"0A149;>>>%.DIC<H7=>;?? C;("(;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;??  ? w" ??              ?? 7      !1AQ"aq2???#?BRr?3Cb?????             ?? '        !1"AQ2Raq???? ? ??{?????>?"7B?7!1???????Z e{????ax??5??CC??-Du? ??X?)Y!??=R@??g?????T??c????f?Wc??eCi?l?????5s??\E???6I??(?x?^???=??d?#?itoi?{;? ??G.......

    ------=_Part_0_2633821.1170785251635--

## Managing SOAP headers and SOAP attachments programmatically

This section illustrates how to manage the Oracle Communications Services Gatekeeper required SOAP headers and SOAP attachments when you are using WebLogic Server and WebLogic Server tools to generate stubs for your Web Services clients. If you are using a different environment, the steps you need to take to accomplish these tasks will be different.

For an overview of using WebLogic Server to create Web Service clients, see the sections discussing invoking Web Services in Oracle WebLogic Server Programming Web Services for WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/webserv/.

The following examples show particularly the use of a SOAP message handler.

These examples show the use of a single message handler to add both SOAP Headers and SOAP attachments.

The WebLogic Server environment relies heavily on using supplied Ant tasks. In Listing 3-9 a supplied Ant task, `clientgen`, is added to the standard build.xml file. A handler configuration file, SOAPHandlerConfig.xml is added as the value for the handlerChainFile attribute. SOAPHandlerConfig.xml is shown in Listing 3-10.

Listing 3-9 Snippet from build.xml

    <clientgen

      wsdl="${wsdl-file}"

      destDir="${class-dir}"

      handlerChainFile="SOAPHandlerConfig.xml"

      packageName="com.bea.wlcp.wlng.test"

      autoDetectWrapped="false"

      generatePolicyMethods="true"

    />

The configuration file for the message handler contains the handler-name and the associated handler-class. The handler class, `TestClientHandler`, is described in Listing 3-11.

Listing 3-10 SOAPHandlerConfig.xml

    <weblogic-wsee-clientHandlerChain

      xmlns="http://www.bea.com/ns/weblogic/90"

      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xmlns:j2ee="http://java.sun.com/xml/ns/j2ee">

      <handler>

        <j2ee:handler-name>clienthandler1</j2ee:handler-name>

        <j2ee:handler-class>

          com.bea.wlcp.wlng.client.TestClientHandler

        </j2ee:handler-class>

      </handler>

    </weblogic-wsee-clientHandlerChain>

`TestClientHandler` provides the following functionality:

- Adds a Session ID to the SOAP header, see Session Management. The session ID is hardcoded into the member variable sessionId.
- Adds a service correlation ID to the SOAP header. See Service Correlation for more information.
- Adds a SOAP attachment in the form of a MIME message with content-type text/plain. See SOAP attachments for more information.
Listing 3-11 TestClientHandler

    package com.bea.wlcp.wlng.client;

    import javax.xml.rpc.handler.Handler;

    import javax.xml.rpc.handler.HandlerInfo;

    import javax.xml.rpc.handler.MessageContext;

    import javax.xml.rpc.handler.soap.SOAPMessageContext;

    import javax.xml.soap.*;

    import javax.xml.namespace.QName;

    public class TestClientHandler implements Handler{

      public String sessionId = "myID";

      public String SCID = "mySCId";

      public String contenttype = "text/plain";

      public String content = "The content";

      public boolean handleRequest(MessageContext ctx) {

        if (ctx instanceof SOAPMessageContext) {

          try {

            SOAPMessageContext soapCtx = (SOAPMessageContext) ctx;

            SOAPMessage soapmsg = soapCtx.getMessage();

            SOAPHeader header = soapCtx.getMessage().getSOAPHeader();

            SOAPEnvelope envelope =

              soapCtx.getMessage().getSOAPPart().getEnvelope();

            // Begin: Add session ID

            Name headerElementName = envelope.createName("session","",

              "http://schemas.xmlsoap.org/soap/envelope/");

            SOAPHeaderElement headerElement =

              header.addHeaderElement(headerElementName);

            headerElement.setMustUnderstand(false);

            headerElement.addNamespaceDeclaration("soap",

              "http://schemas.xmlsoap.org/soap/envelope/");

            SOAPElement sessionId = headerElement.addChildElement("SessionId");

            sessionId.addTextNode(sessionId);

            // End: Add session ID

            // Begin: Add Combined Services ID

            Name headerElementName = envelope.createName("SCID","",

              "http://schemas.xmlsoap.org/soap/envelope/");

            SOAPHeaderElement headerElement =

              header.addHeaderElement(headerElementName);

            headerElement.setMustUnderstand(false);

            headerElement.addNamespaceDeclaration("soap",

              "http://schemas.xmlsoap.org/soap/envelope/");

            SOAPElement sessionId = headerElement.addChildElement("SCID");

            sessionId.addTextNode(SCID);

            // End: Add Combined Services ID

            // Begin: Add SOAP attachment

            AttachmentPart part = soapmsg.createAttachmentPart();

            part.setContent(content, contenttype);

            soapmsg.addAttachmentPart(part);

            // End: Add SOAP attachment

          } catch (Exception e) {

            e.printStackTrace();

          }

        }

        return true;

      }

      public boolean handleResponse(MessageContext ctx) {

        return true;

      }

      public boolean handleFault(MessageContext ctx) {

        return true;

      }

      public void init(HandlerInfo config) {

      }

      public void destroy() {

      }

      public QName[] getHeaders() {

        return null;

      }

    }