This component is used to expose an Event Process as a Web Service in the Web Service Gateway (which is a web application deployed in Peer Server). WSDL will be generated when this component is launched and the URL of the WSDL can be used by Web Service clients to access the Web Service. The client’s request is directly delivered to the output port of the WSStub component and this request can be passed to the components connected to WSStub output port in the Event Process. The connected components process the message and the response is sent to the input port of the WSStub component. The response received on the input port is sent back to the client.
Points to note
1. When WSStub component is configured to launch on HA (High Availability) Peer Servers
If both Primary and Secondary Servers are on the same machine
Initially, if WSStub is launched on the Primary Server, the generated WSDL URL contains Primary Server’s jetty port number. In case of Primary Server failover, the Secondary Server becomes Active and relaunches the component. WSDL will be regenerated and if the Secondary Server uses a different jetty port then the WSDL URL is changed. The clients have to be reconfigured to use new URL in this case.
To avoid this situation, it is recommended to use same jetty ports for both Primary and Secondary Peer Servers.
Jetty service will be started only after the server is started successfully. In case of HA, only one server will be active at a given time and the Jetty Server will be running only in the active server and there will be no bind exceptions even if both the servers use same port number for Jetty.
If both Primary and Secondary servers are on different machines
In this case if the failover happens the hostname/IP address in the WSDL URL will be changed. So the clients have to be reconfigured accordingly.
2. HTTP headers are received from the gateway as message properties with the header name
3. prefixed with http_. Example: http_Content-Type.
The custom property sheet of WSStub is shown in Figure 1 and the properties are explained below.
Figure 1: Sample stub component configuration
Context Name
Name of the context which is created for this Web Service. Web Service stub component accepts requests sent to this context. The Effective End Point URL is http://<peerserverip>:<httpport>/<ContextRoot>/ContextName, httpport value for default Peer Server (profile1/FPS) is 1880 by default. Context name is a mandatory parameter to use WSStub.
Context Description
A brief description of the context can be specified here.
End Point URI
This is the URI of the Admin context. To deploy/undeploy a Web Service in Axis engine, Fiorano uses WSDD based administration with admin context FAdminService.
Operation Details
Operation related information can be configured here.
Figure 2: Operation details editor
Operation Name
Name of the Web Service operation. This operation name can be used by a Web Service client to invoke the Web Service.
Operation Description
A brief description of the Operation can be provided here.
Note: Currently, there is no multiple operation support in WSStub component. In case if multiple operations have to be handled, one may split up the operations across multiple Fiorano Event Processes with the respective input/output schema configured in the WS Stub component.
FES URL
The URL of Enterprise Server to which the Peer Server on which the component is running is connected.
FES Backup URL
The alternate URL that should be tried for connecting to the Enterprise Server if the Enterprise Server cannot be connected to using the URL mentioned against property FES URL.
Note: In case of Enterprise Servers in HA mode, this should point to Secondary Server URL if the primary is set against Server URL property and vice-versa.
Username
User name that should be used to connect to the enterprise server.
Password
Password that should be used to connect to the enterprise server.
Execution Details
Request execution details can be configured here.
Figure 3: Execution Details
Execution Timeout
WSStub component receives client request on its output port and sends the request message to the connected components. After the processing is completed by the connected components response message is sent to WSStub input port and from there it will be sent to the client.
WSStub component accepts the response if it reaches before the timeout period. If no response is received, on timeout Error message will be sent to the client saying No message received till the timeout period.
Note: Request will be processed by the connected components in the Event Process even after the timeout but the response is not sent back to the client by WSStub.
Execution Timeout of 0 indicates infinite timeout.
Request Timeout
This value is set as Time to live property on the request message. The request message will be discarded after the timeout.
0 indicates infinite time.
Close after each request
If this property is set to yes, all the resources (excluding connection) used by the component will be cleaned up after processing the request and recreated for the next request.
Request XSD
The XML schema of Web Service request can be configured here. Schema Editor will be launched where the header and body schemas of the request can be specified.
Figure 3: Stub1 – Request Xsd
Provide the appropriate schemas for request and for soap headers, if any. Provide appropriate imported schemas in External XSDs tab for resolving the schemas.
Response XSD
The XML schema of Web Service response (headers and body) can be configured here.
Failure XSD
The XML schema of error can be configured here.
Request/Response Security
Request Security
Username Token
Determines whether the server should perform Username token identification or not.
Order of Username Token
Determines the order of the UsernameToken security function. The order of a security function determines when this function will be applied when multiple security functions are being used.
Password Callback Class
This is needed by the security functions to get the password and to verify the username/password pair. The password callback class should implement org.apache.ws.security.WSPasswordCallback class. This Password Callback class should be the fully qualified name of the class. The jar which contains the password callback class must be placed in '%FIORANO_HOME%\esb\server\jetty\fps\webapps\bcwsgateway\WEB-INF\lib'.
Timestamp
Determines whether the soap request has timestamp in security header or not. In this case, the message is valid up to 5 minutes or 300 seconds after the creation of the message.
Timestamp Precision in MilliSeconds
If this is set, timestamps will have precision in milliseconds. Otherwise it will be seconds.
Order of Timestamp
Specifies the order of the Timestamp security function. The order of a security function determines when this function will be applied when multiple security functions are being used.
Encrypt
Determines whether the soap request (or some parts of it) is encrypted or not.
Order of Encrypt
Specifies the order of the encrypt security function. The order of a security function determines when this function will be applied when multiple security functions are being used.
Encryption Properties File Name
The name of the crypto property file to use for decryption of the soap request. If this parameter is not specified and if both the "Signature Properties filename" and "Signature" are set to yes, then the decryption function uses signature property file. Otherwise the handler throws an AxisFault. The properties file must be placed in '%FIORANO_HOME%\esb\server\jetty\fps\webapps\bcwsgateway\WEB-INF\classes'
An example properties file content:
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.file=C:\\Documents and Settings\\Fiorano\\Desktop\\fiorano.ks
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=fioranopass
org.apache.ws.security.crypto.merlin.keystore.alias=fiorano
org.apache.ws.security.crypto.merlin.alias.password=fioranopass
The properties descriptions :
org.apache.ws.security.crypto.provider : implementation class for security provider. Fiorano internally uses
bouncycastle, to use the same this property must be set to "org.apache.ws.security.components.crypto.Merlin". To use
other providers, the provider jar must be placed
in '%FIORANO_HOME%\esb\server\jetty\fps\webapps\bcwsgateway\WEB-INF\lib' and fully qualified name of
appropriate provider class has to be set for this property.
org.apache.ws.security.crypto.merlin.file : The path to the keystore file.
org.apache.ws.security.crypto.merlin.keystore.type : The keystore type, for example JKS for the Java key store. Other
keystore type, such as pkcs12 are also possible but depend on the actual Crypto implementation.
org.apache.ws.security.crypto.merlin.keystore.password : The password to read the keystore. If this property is not set,
then the pwcallbackproperty must be defined.
org.apache.ws.security.crypto.merlin.keystore.alias : The alias name under which the private key/certificate stored in keystore
org.apache.ws.security.crypto.merlin.alias.password : Password for private key/certificate inside keystore stored under
given alias (not used for encryption)
Signature
Determines whether the soap request (or some parts of it) is signed or not.
Order of Signature
Specifies the order of the Signature security function. The order of a security function determines when this function will be applied when multiple security functions are being used.
Signature Properties File Name
The name of the crypto property file to use for SOAP Signature. Please see the description of "Encryption Properties filename" for the details of the properties file.
SAML
Determines whether the server should perform SAML Token identification or not.
Order of SAML
Specifies the order of the SAML security function.The order of a security function determines when this function will be applied when multiple security functions are being used.
Signed SAML
If Signed SAML is used at client side for request, then the client performs two actions inserting a SAML Token (unsigned) and an associated Signature. So define both the actions SAML Unsigned and Signature here to resolve these security headers.
Response Security
Username Token
Determines whether the server should perform Username Token Identfication on responce or not. If this property is set, the the responce from server contains Username and Password security headers.
Order of Username Token
Determines the order of the UsernameToken security function. The order of a security function determines when this function will be applied when multiple security functions are being used.
Password Callback Class
This is needed by the security functions to get the password and to verify the username/password pair. The password callback class should implement org.apache.ws.security.WSPasswordCallback class. This Password Callback class should be the fully qualified name of the class. The jar which contains the password callback class must be placed in '%FIORANO_HOME%\esb\server\jetty\fps\webapps\bcwsgateway\WEB-INF\lib'.
Timestamp
Specifies whether the soap response from server should contain timestamp header or not.
Timestamp Precision in MilliSeconds
If this is set, timestamps will have precision in milliseconds. Otherwise it will be seconds.
Order of Timestamp
Specifies the order of the Timestamp security function. The order of a security function determines when this function will be applied when multiple security functions are being used.
User
This property is used as username for the UsernameToken security function. It is also used as the alias name in the keystore to get user's certificate or private key to perform signing for the Signature security function. It is also used as the fallback for the encryption security function in case of "Encryption User" is null and "Encryption" in response is set to yes.
Password Type
Password type: The Password type can be either PasswordText or PasswordDigest
PasswordText
Password is sent in raw text format with in the security header of the soap response.
PasswordDigest
Password is sent in digest format with in the security header of the soap response.
Nonce Security Element
Specifies whether to use nonce element in the security header or not. When UsernameToken security function is used, then nonce security element can be employed to prevent message replay attacks. A nonce is a random value that the client creates to include in each UsernameToken that it sends. Although using a nonce is an effective countermeasure against replay attacks, it requires server to maintain a cache of used nonces, consuming server resources.
Created Security Element
Specifies whether to use Created element in the security header or not. This element denotes the time of creation of a nonce. Combining a nonce with a creation timestamp has the advantage of allowing a server to limit the cache of nonces to a "freshness" time period, establishing an upper bound on resource requirements.
Encrypt
Determines whether the server should encrypt the soap response (or some parts of it) or not.
Order of Encrypt
Specifies the order of the encrypt security function. The order of a security function determines when this function will be applied when multiple security functions are being used.
Encryption Properties File Name
The name of the crypto property file to use for SOAP Encryption in response. If this parameter is not specified and if both "Signature Properties filename" and "Signature" in response are set, then the encryption function uses signature property file. Otherwise the handler throws an AxisFault. The properties file must be placed in '%FIORANO_HOME%\esb\server\jetty\fps\webapps\bcwsgateway\WEB-INF\classes'. Please see the description of "Encryption Properties filename" in request security for the details of the crypto properties file.
Encryption User
Username for the encryption function. The encryption function uses the public key of this user's certificate. If this parameter is not set, then the encryption function falls back to the "User" parameter to get the certificate. The encrypt function will not authenticate user. So there is no need to set any password call back class for encrypt.
Encryption Parts
Parameter specifies which parts of the response shall be encrypted. The value of this parameter is a list of semi-colon separated element names that identify the elements to encrypt. An encryption mode specifier and a namespace identification, each inside a pair of curly brackets, may precede each element name. The encryption mode specifier is either {Content} or {Element}. 'Element' encryption mode will encrypt the entire element including start and end tags. 'Content' encrypt mode will encrypt only the content of the specified element. The default encryption mode is 'Content'.
For example if we set "{Element}{http://example.org/paymentv2}CreditCard;{}{}UserName" list to this property, then the first entry of the list identifies the element CreditCard in the namespace http://example.org/paymentv2, and will encrypt the entire element. In the second entry the encryption modifier and the namespace identifier are omitted. In this case the encryption mode defaults to Content and the namespace is set to the SOAP namespace.
The element name, the namespace identifier, and the encryption modifier are case sensitive. To specify an element without a namespace use the string Null as the namespace name (this is a case sensitive string). If no list is specified, the handler encrypts the SOAP Body in Content mode by default.
Encryption Key Identifier
Select the key identifier type to use.
DirectReference
The security function takes the signing certificate, converts it to a BinarySecurityToken, puts it in the security header. Thus the whole signing certificate is transferred.
X509KeyIdentifier
The encryption method uses the public key associated with this certificate to encrypt the symmetric key used to encrypt data. The certificate is converted into a KeyIdentifier token and sent to the server. Thus the complete certificate data is transferred.
SKIKeyIdentifier
The security function uses SKIKeyIdentifier.
IssuerSerial
The encryption method uses the public key associated with this certificate to encrypt the symmetric key used to encrypt data. The issuer name and the serial number of the signing certificate are sent to the server.
Signature
Determines whether the soap response (or some parts of it) should be signed or not.
Order of Signature
Specifies the order of the Signature security function. The order of a security function determines when this function will be applied when multiple security functions are being used.
Signature Properties File Name
The name of the crypto property file to use for SOAP Signature. Please see the description of "Encryption Properties filename" for the details of the properties file.
Signature Parts
Parameter specifies which parts of the request shall be signed. Please see the description of "Encryption Parts" for the syntax.
Signature Key Identifier
Select the key identifier type to use. Please see the description of "Encryption Key Identifier" for the descriptions of key identifiers.
SAML
Determines whether the server sholud perform SAML Token Identification or not.
Order of SAML
Specifies the order of the SAML security function. The order of a security function determines when this function will be applied when multiple security functions are being used.
Signed SAML
Specifies whether to use signed SAML or unsigned SAML. If Signed SAML is used, then server performs two actions inserting a SAML Token (unsigned) and an associated Signature. So define both the actions SAML Unsigned and Signature at client side to resolve these security headers. If Signed SAML is used, the signature properties should be specified in this panel with out selecting the property "Signature WS-Security".
SAML Properties File Name
The name of the SAML properties file. This file must be placed in '%FIORANO_HOME%\esb\server\jetty\fps\webapps\bcwsgateway\WEB-INF\lib'.
Enable Authentication
Basic authentication support for the Web Services can be provided using this property.
Before enabling this property in WSStub, basic authentication has to be enabled in FPS Jetty Server and in bcwsgateway webapp (FIORANO_HOME/esb/server/jetty/fps/webapps/bcwsgateway). Procedure to enable basic authentication in Jetty Server and in the webapp is explained below.
Enabling Basic Authentication in Jetty Server
1. Stop the FPS Server if it is running.
2. Open FPS profile in Fiorano Studio and navigate to FPSàFioranoàEsbàJetty.
3. Select the Jetty mbean. In the properties window, set the property Basic Authentication to yes and give the fully qualified path of Realm.properties file against the property Realm Properties. More information on Realms and Realm.properties file content is discussed in the next section.
4. Save the profile.
Figure 4: Enabling Basic Authentication in FPS Jetty server
Enabling Basic Authentication in webapp
1. Open Web.xml file located at FIORANO_HOME/esb/server/jetty/fps/webapps/bcwsgateway/WEB-INF.
2. Uncomment the security-constraint and login-config elements and save the file.
3. Delete the Peer Server cached profile from FES runtime by deleting the folder FIORANO_HOME/runtimedata/EnterpriseServers/<Profile Name>/FES/peers/<peer profile>.
4. Start the FPS server.
The basic authentication is enabled in FPS Jetty Server and in the webapp. Now the authentication can be enabled in WSStub by setting the value of Enable authentication property to yes. Provide a set of username and password which is present in Realm.properties file.
Note: To confirm the authentication, when the WSStub component is launched right-click the component and select View WDSL option. Web browser prompts the user to enter the username and password to display the WSDL.
When the authentication is enabled in WSStub, client can access the Web Service only if it uses the basic authentication with correct credentials.
UserName
Username to be used by the WSStub component while deploying the Web Service. The entry for this user name has to be present in Realm.properties file. If this user name is not present, the component will not launch.
Password
Password to be used by the WSStub component while deploying the Web Service. If this password is not present in Realm.properties file the component will not launch.
Security realms allow securing the web applications against unauthorized access. Protection is based on authentication (identifying who is requesting access to the webapp) and access control (restricting what can be accessed and how it is accessed within the webapp).
A webapp statically declares its security requirements in the web.xml file. Authentication is controlled by the <login-config> element. Access controls are specified by <security-constraint> and <security-role-ref> elements. When a request is received, the web container checks if the user performing the request is authenticated and if the user has a role assignment that permits access to the requested resource. Access to the resource is allowed only when the user is authorized and has the required permissions.
A realm has a unique name, and is composed of a set of users. Each user has authentication information (Example: a password) and a set of roles associated.
More than one realm can be configured depending on the needs.
Fiorano uses a simple realm whose authentication and authorization information is stored in a properties file. Each line in the file contains a username, a password, and 0 (zero) or more role assignments. The format is:
username: password[,rolename ...]
where:
username is the user's unique identity
password is the user's password
rolename is the user's role
Sample content of Realm.properties file is shown below:
admin: admin,admin
user: password,user
guest: guest,read-only
The input schema is auto generated based on the configuration provided. If only the response schema is provided, then that is schema set as the input. If headers are also provided, then the schema is a SOAP schema with header and body being explicitly defined based on the root elements selected.
The output schema is auto generated based on the configuration provided. If only the request schema is provided, then that schema set as the output. If headers are also provided, then the schema is a SOAP schema with header and body being explicitly defined based on the root elements selected.
Figure 5: Scenario demonstration
Figure 5 demonstrates how WSStub can be used to deploy the Event Process as Web Service.
In the flow, WSStub is connected to an SMTP component. WSStub component sends the client requests to SMTP and gets the SMTP response which is sent back to the client. Request XSD of WSStub is same as that of SMTP component’s input port schema, Response XSD is same as SMTP component’s output port schema and Failure XSD is same as the error port schema of SMTP component.
When the Event Process is launched, it gets deployed as Web Service with context name and operation name specified in the CPS. On right-clicking and selecting view wsdl, the user can view the wsdl for this WSStub in a web browser.
A WebserviceConsumer component can be configured to invoke this Web Service by providing the URL of this wsdl (in the Managed Connection Factory panel of WS consumer's CPS) and by selecting the Web Service Operation (In Interaction Configuration Panel).
Sample request and response to WebserviceConsumer component which accesses the deployed Web Service is shown below.
Figure 6: Sample Request
Figure 7: Sample Response
For SSL to work properly the JDK version using should be greater than 1.5.0_08 and the jars present in JDK_HOME/jre/lib/ext are to be copied to $FIORANO_HOME/esb/lib/ext.