This chapter presents a high-level description of the SOAP mechanisms and explains how to use this functionality to create services that interact with Oracle Communications Services Gatekeeper (Services Gatekeeper.)
The SOAP-based interfaces are based on the Parlay X standards, and additional Extended Web Services interfaces that cover functionality which is not supported by Parlay X.
See Services Gatekeeper Concepts for a complete list of the SOAP-based interfaces supported by Services Gatekeeper. These interfaces are explained in detail in the chapters that follow.
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. See "Understanding the Extended Web Services Common Definitions" for details.
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 do 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 Attachments Programmatically".
See "Adding a SOAP2SOAP Communication Services" for information on how to create and deploy a SOAP2SOAP communication service.
If your application is using the SOAP-based interfaces to interact with Services Gatekeeper, there are four types of elements you may need to add to your application's SOAP messages to Services Gatekeeper.
In order to secure 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. Services Gatekeeper leverages the WebLogic Server Web services Security (WS-Security) framework to process this information.
Note:
WS-Security provides three modes of providing security between a Web service client application and the Web service itself for message level security: Authentication, Digital Signatures, and Encryption. See "Securing and Administering Web Services" in see Oracle Fusion Middleware Security and Administrator's Guide for Web Services for an overviewServices Gatekeeper supports three authentication types:
The type of token that the particular 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.
Example 24-1 WSDL fragment showing Policy
<s0:Policy s1:Id="Auth.xml">
<wssp:Identity> <wssp:SupportedTokens> <wssp:SecurityToken TokenType="http://docs.example.com/wss/2004/01/oasis200401wssusernametoken profile1.0#UsernameToken"> <wssp:UsePassword Type="http://docs.oasisopen.org/wss/2004/01/oasis200401wssusernametoken profile1.0#PasswordText"/> </wssp:SecurityToken> <wssp:SecurityToken TokenType="http://docs.oasisopen.org/wss/2004/01/oasis200401wssx509token profile1.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).Below are examples of the three types of authentication that can be used with Services Gatekeeper.
In the Username Token mechanism, which is specified by the use of the <wsse:UsernameToken> element in the header, authentication is based on a user name, 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 Services Gatekeeper evaluates the username using the associated authentication provider. The authentication provider connects to the Services Gatekeeper database and authenticates the username and the password. In the database, passwords are stored as MD5 hashed representations of the actual password.
Example 24-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 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
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 Services Gatekeeper verifies the authenticity of X.509 tokens and maps them to valid Services Gatekeeper users.
Note:
While it is possible to use the out-of-the-box keystore configuration in 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 discussion on configuring identity and trust in Oracle Fusion Middleware Securing Oracle WebLogic Server at:http://download.oracle.com/docs/cd/E15523_01/web.1111/e13707/identity_trust.htm
The x.509 certificate common name (CN) for an application must be the same as the account user name, which is the string that was referred to as the applicationInstanceGroupId in previous versions of Services Gatekeeper. This is provided by the operator when the account is provisioned.
To authenticate using x.509 certificates:
Create a web service security configuration.
For details, see "Create a Web service security configuration" in Oracle WebLogic Server Administration Console Online Help.
Generate key pair for the client :
% keytool -genkey -alias client_cert_x509 -keyalg RSA -keysize 1024 -keypass ClientKey -keystore client_Identity.jks -storepass ClientKey
Export the self-signed certificate:
% keytool -genkey -alias server_cert_x509 -keyalg RSA -keysize 1024 -keypass ServerKey -keystore ServerIdentity.jks -storepass ServerKey
Generate the key pair for the server:
keytool -genkey -alias server_cert_x509 -keyalg RSA -keysize 1024 -keypass ServerKey -keystore ServerIdentity.jks -storepass ServerKey
Export the self-signed certificate:
% keytool -export -rfc -alias server_cert_x509 -file ServerCert.cer -keystore ServerIdentity.jks -storepass ServerKey
Import the trust certificates:
% keytool -import -v -trustcacerts -alias client_cert_x509 -file ClientCert.cer . -keystore C:\ocsg510ga\JDK160~1\jre\lib\security\cacerts -storepass changeit keytool -import -v -trustcacerts -alias server_cert_x509 -file ServerCert.cer . -keystore C:\ocsgversion\JDKversion\jre\lib\security\cacerts -storepass changeit
Configure the certificates in the Administration Console by pointing the server to the certificates you created in Step 5:
C:\ocsgversion\JDKversion\jre\lib\security\ServerCert.cer
You can use x.509 certificates to establish identity.
For details, see ”Use X.509 certificates to establish identity” in Oracle WebLogic Server Administration Console Online Help.
Example 24-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>
Using WebLogic Server's WSSE implementation, Services Gatekeeper supports SAML versions 1.0, 1.1, and 2.0. The versions are similar.
See "Using SAML Assertions to Access Resources" in Services Gatekeeper OAuth Guide for more information on using SAML with OAuth.
For an overview of the differences between versions 1.0 and 1.1, see:
http://www.oasis-open.org/committees/download.php/3412/sstc-saml-diff-1.1-draft-01.pdf
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 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 discussion on SAML token profile support in Oracle Fusion Middleware Understanding Security for Oracle WebLogic Server at:
http://download.oracle.com/docs/cd/E15523_01/web.1111/e13710/archtect.htm
Example 24-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>
By default Services Gatekeeper AT server waits 3 seconds to establish a connection with an application endpoint before giving up on the connection, and 30 seconds after establishing the connection before deciding that a reply will never come. The -Dwlng.ws.callback.connect_timeout java property setting controls the time limit for requesting a connection and -Dwlng.ws.callback.read_timeout controls the reply time limit. Change these settings if your Services Gatekeeper implementation requires different time limits by adding these Java arguments to your Middleware_Home/user_projects/domains/domain_name/bin/startWebLogic.sh script:
-Dwlng.ws.callback.connect_timeout=time_in_miliseconds -Dwlng.ws.callback.read_timeout=time_in_miliseconds
In some cases the service that an application provides to its end-users may involve accessing multiple Services Gatekeeper communication services. For example, a mobile user might send an SMS to an application asking for the pizza restaurant 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 restaurant, and then sends the user an MMS with all the appropriate information. Three 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, Services Gatekeeper uses a service correlation ID, or SCID. This is a string that is captured in all the CDRs and EDRs generated by 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 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, 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 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.
When the scid element is used, it should be on the same level as the session element in the SOAP header.
Parameter tunneling is a feature that allows an application to send additional parameters to 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 it.
See the discussion on using SOAP parameter tunneling in Services Gatekeeper Extension Developer's Guide for more information parameter tunneling.
See the appropriate sections in Services Gatekeeper Communication Service Reference Guide for descriptions of the tunneled parameters that are applicable to your communication service.
In some communication services request payloads are sent as SOAP attachments. Example 24-6 below shows a Multimedia Messaging sendMessage operation that contains an attachment carrying a jpeg image.
Example 24-6 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--
This section illustrates how to manage the 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, these steps probably do not apply.
For an overview of using Oracle Fusion Middleware to create Web service clients, see the discussion on Oracle Fusion Middleware in Oracle Fusion Middleware Introducing Web Services at:
http://download.oracle.com/docs/cd/E15523_01/web.1111/e14294/toc.htm
These examples show how to use a single message handler to add both SOAP Headers and SOAP attachments.
The WebLogic Server environment relies heavily on using supplied Ant tasks. Example 24-7 shows the clientgen Ant task added to the standard build.xml file.
Example 24-7 Snippet from build.xml
<clientgen
wsdl="${wsdl-file}"
destDir="${class-dir}"
handlerChainFile="SOAPHandlerConfig.xml"
packageName="com.bea.wlcp.wlng.test"
autoDetectWrapped="false"
generatePolicyMethods="true"
/>
A handler configuration file, SOAPHandlerConfig.xml is added as the value for the handlerChainFile attribute. Example 24-8 show a SOAPHandlerConfig.xml file.
Example 24-8 SOAPHandlerConfig.xml
<weblogic-wsee-clientHandlerChain
xmlns="http://www.example.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 for SOAP, RESTful, and OneAPI Interfaces". The session ID is hardcoded into the member variable sessionId.
Adds a service correlation ID to the SOAP header. See "Understanding How Service Correlation Orchestrates Services" for more information.
Adds a SOAP attachment in the form of a MIME message with content-type text/plain. See "Understanding SOAP Payload Attachments" for more information.
The configuration file for the message handler contains the handler-name and the associated handler-class. The handler class, TestClientHandler, is shown in Example 24-9.
Example 24-9 TestClientHandler
package com.example.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;
}
}