| Oracle® Communications Services Gatekeeper Application Developer's Guide Release 5.0 Part Number E16611-02 |
|
|
View PDF |
| Oracle® Communications Services Gatekeeper Application Developer's Guide Release 5.0 Part Number E16611-02 |
|
|
View PDF |
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 Services Gatekeeper and the application.
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".
If your application is using the a SOAP-based facade (set of 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 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 securing web services, see "Securing and Administering WebLogic Web Services" in Oracle Fusion Middleware Security and Administrator's Guide for Web Services at:http://download.oracle.com/docs/cd/E15523_01/web.1111/b32511/weblogic.htm
Services 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 2-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).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 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 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 2-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 "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 UserName, 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.
Example 2-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 and 1.1. The versions are similar. For an overview of the differences between the versions, 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 "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 2-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>
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 Services Gatekeeper. The session allows 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 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.
An application establishes a session in 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 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.
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 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 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 the it.
See the appropriate sections in the Communication Service Guide for descriptions of the tunneled parameters that are applicable to your communication service.
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.
Example 2-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.
In some communication services, the request payload are sent as SOAP attachments. Example 2-8 below shows a Multimedia Messaging sendMessage operation that contains an attachment carrying a jpeg image.
Example 2-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--
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, the steps you need to take to accomplish these tasks will be different.
For an overview of using Oracle Fusion Middleware to create Web Service clients, see "Oracle Fusion Middleware" in Oracle Fusion Middleware Introducing Web Services at:
http://download.oracle.com/docs/cd/E15523_01/web.1111/e14294/toc.htm
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 Example 2-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 Example 2-10.
Example 2-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 Example 2-11.
Example 2-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.
Example 2-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;
}
}
|
 Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|