|
|
In order to interact with Network Gatekeeper, applications 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 Multimedia Messaging or WAP Push, they must send their message payload as a SOAP attachment. The following chapter presents a high-level description of these mechanisms, and how they function to manage the interaction between Network Gatekeeper and the application. It covers:
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 traffic paths. Developers should use Axis 1.4 or newer if they wish to use Axis. |
For examples using the WebLogic Server environment to accomplish these sorts of tasks, see the final section of this chapter:
There are three types of elements you may need to add to your application's SOAP messages to Network Gatekeeper.
In order to secure Network 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. Network Gatekeeper leverages the WLS 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 WLS WS Security, see Programming Web Services of WebLogic Server, the Configuring Security chapter. |
Network Gatekeeper supports three authentication types:
The type of token that the particular Network 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.
<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 Network 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:
There are two more optional elements in Username Token, introduced to provide a countermeasure for replay attacks:
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 Network Gatekeeper evaluates the username using the associated authentication provider. The authentication provider connects to the Network Gatekeeper database and authenticates the username and the password. In the database, passwords are stored as MD5 hashed representations of the actual password.
<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 string that was called the Application Instance Group ID in Network Gatekeeper 2.2. The Password part is the password associated with this UserName when the application was provisioned in Network 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. See http://dev2dev.bea.com/pub/advisory/30.
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
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 Network Gatekeeper verifies the authenticity of X.509 tokens and maps them to valid Network Gatekeeper users.
| Note: | While it is possible to use the out-of-the-box keystore configuration in Network 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, refer to Securing WebLogic Server, the Configuring Identity and Trust section. |
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 Network Gatekeeper. This is provided by the operator when the account is provisioned.
<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>
Network 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 Network Gatekeeper, using the WebLogic Security framework) then evaluates the trustworthiness of the assertion, using one of two confirmation methods.
For more information on these confirmation methods, see " SAML Token Profile Support in WebLogic Web Services" in Understanding WebLogic Security.
<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>
Before an application can begin sending requests through Network Gatekeeper, it must establish a session, using the Session Manager Web Service. The session allows Network 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 logs out. The session is good for an entire WebLogic Network Gatekeeper domain, across clusters, and covers all traffic paths to which the application has contractual access
An application establishes a session in Network 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 a Network 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.
<Session>
<wlng:SessionId>app:-2810834922008400383</wlng:SessionId>
</Session>
In some cases the service that an application provides to its end-users may involve accessing multiple Network Gatekeeper traffic paths. 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 Network Gatekeeper traffic paths are involved in executing what for the application is a single service. In order to be able to correlate the three traffic path requests, Network Gatekeeper uses a Service Correlation ID, or SCID. This is a string that is captured in all the CDRs and EDRs generated by Network 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 Network 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, Network 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 Network 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. In version 3.0, this option is available only with enhanced traffic paths.
<scid id="myid"/>
Parameter tunneling is a feature that allows an application to send additional parameters to Network 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 interface that the application is using and can be seen as an extension to the application-facing interface.
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 have 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.
<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.
The payloads for Multimedia Messages and WAP Push messages in Network Gatekeeper are sent as SOAP attachments. Listing 3-8 below shows a Multimedia Messaging sendMessage operation that contains an attachment carrying a jpeg image.
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 Network 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 Invoking Web Services chapter of Programming Web Services for WebLogic Server. The following examples show particularly the use of a SOAP message handler as covered in that chapter.
| Note: | These examples show the use of a single message handler to add both SOAP Headers and SOAP attachments. Chains of custom message handlers are not supported in Network Gatekeeper. |
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.
<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.
<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:
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;
}
}
|