Spanish version
IMPORTANT: This implementation is deprecated since GxXev1 U2, and it is neccessary to configure using WCF
Introduction
Version: GX X Ev1 - Generator .Net.
As from this version it is possible to configure the .Net generator to use native serialization support to consume and provide SOAP Web Services. This enables the use of specific .Net features implemented on this infrastructure, in particular, the use of Web Service Enhancements (WSE) which make it possible to use protocols such as WS-Security:
Advantages
.Net Framework 2.0 makes it possible to use WSE 3.0; one of the design concepts handled by WSE 3.0 is that the configuration of the communication policies with Web Services can be determined at the time of deployment and not when implementing the application. On this basis it implements a set of features that enable you to establish these policies once the applications have been compiled using configuration files. For more information, read: http://msdn.microsoft.com/en-us/library/ms977317.aspx
Consume web services
When GeneXus is configured to generate Web Services in this way, properties are enabled to specify a communication policy that is declared in a configuration file. Later on, all changes to the communication protocol are made by changing this file without the need to regenerate the application
Properties
Environment properties:
- Use native soap support –Determines the serialization support and SOAP communication to use.
o Yes – Uses the .Net Framework infrastructure to serialize SOAP messages.
o No – Generated serialization support.
- Use WSE
o Yes – Enables the use of WSE 3.0 over the native serialization support; WSE 3.0 must be installed.
o No
NOTE: The WSE 3.0 DLL must be installed and the DLL in the bin directory (Microsoft.Web.Services3.dll).
Properties of the external objects' methods of Web Service type:
- WSE policy name- Name of the communication policy used to consume this Web Service method. This policy must be declared in a configuration file.
Configuration file:
The configuration items necessary for activating the WSE are automatically generated in the web.config. Among them is included the file where the communication policies are declared, which is called “wse3policyCache.config”.
In this file, which must be created by the developer, the characteristics of each configuration policy are declared.
Example: to defile a policy called “TestClientPolicy” that sends the username and password (with no encryption), the following is declared:
<policies xmlns="http://schemas.microsoft.com/wse/2005/06/policy"> <policy name="TestClientPolicy">
<usernameOverTransportSecurity>
<clientToken>
<username username="usuario" password="pass" />
</clientToken>
</usernameOverTransportSecurity>
<requireActionHeader />
</policy>
</policies>
Then, in the external object method of the “WSE Policy Name” property, “TestClientPolicy” is specified as the communication policy with that web service. The WSE infrastructure automatically adds the necessary SOAP headers when messages are serialized based on what has been declared in the configuration file.
Publish Web Services
Both procs with SOAP call protocol and Data Providers enable the “WSE policy name” property, which contains the reference to the configuration policy for the server, declared in the configuration file in the same way as for the client.
Depending on the predefined policy used, it may be necessary to perform a certain validation to authorize the requirement. Taking the example mentioned above, the username and password must be validated in the server. It doesn't have to be implemented in the web service logic itself, as WSE provides a way to add an external class in the pipeline that serves the requirement; this class validates the user before the service is executed. For this particular case, an assembly is defined that performs the validation. A basic example would be as follows:
using System;using System.Web.Services.Protocols;
using Microsoft.Web.Services3;
using Microsoft.Web.Services3.Security.Tokens;
namespace test {
public class SampleUsernameTokenManager : UsernameTokenManager
{
protected override string AuthenticateToken(UsernameToken token)
{
// Implement username/password validation here
bool Valid = (("usuario" == token.Username) && ("pass" == token.Password));
if (Valid)
{
return "usuario";
}
else
{
throw new UnauthorizedAccessException("User validation failed");
}
}
}
}
This is compiled to an assembly that is copied in the BIN.
Next, this manager is declared in the web.config to perform the validation:
<microsoft.web.services3>
<security>
<securityTokenManager>
<add type="test.SampleUsernameTokenManager,SampleUsernameTokenManager"
namespace="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
localName="UsernameToken" />
</securityTokenManager>
</security>
</microsoft.web.services3>
The WSE usually brings several predefined managers and therefore is not neccessary declare (the policy automatically includes them)