Configuring AIF WebServices with mapped x.509 certificates

AIF WebServices needs to be authenticated with a Windows user that is configured in Ax. This can be done with Ntlm authentication. If the Ntlm-authentication is not an option, the X.509 authentication can be an alternative. X.509 certificates can be mapped easily to a windows account and so makes it possible for the client to authenticate as an Windows-user.

The following snapshots can serve as a simple “how-to”-setup the X.509 certificates for the AIF-WebServices.

The IIS-configuration

The anonymous access need to be activated:

The client certificate mapping needs to be activated:

After selecting the certificate, the certificate needs to be mapped to the Windows-account:

The service configuration:

The service configuration is configured to authenticate on the transport level:

and the MapClientCertificateToWindowsAccount attribute is activated:

The client configuration:

The client authentication is configured for transport:

And the configuration points to the X.509 certificate. The clientCertificate-element is documented on msdn.

If your are using a dummy-certificate, you need to implement the RemoteCertificateValidationCallback in the client application as described in this article.

Testing AIF-WebServices with soapUI

The open-source project soapUI (from eviware) is probably the most complete and easiest to use soap testing suite and it’s free. It is a great tool to test AIF-WebServices, too.
Authenticating AIF-Services is in most cases configured to be authenticated with Windows credentials and so with NTLM. So far soapUI only supports NTLMv1 and because of this you need to be sure that your server does support the NTLMv1 which is configured with the LmCompatibilityLevel property in the HKLM\SYSTEM\CurrentControlSet\Control\Lsa hive.
Configuring soapUI for authenticating with Ntlm is quite easy and well documented.
To authenticate with Ntlm to an AIF-WebService you just need to configure the username, password and domain:

and the WS-A the default wsa:To:

On the server side the binding needs to be configured for Ntlm-authentication on transport level. This is by default set to “Windows”:

Now soapUI can consume the AIF-WebService:

Limitations of the Dynamics Ax Service references

Service references are WebService Proxies generated by Ax 2009 with the tool svcutil.exe based on Wsdl files. Creating a Service reference is very easy and well documented on msdn and it was never been easier to consume WebServices with X++ if the Wsdl of the WebService is compatible with Dynamics Ax. Wsdl files are normally generated by the WebService which is in almost every case based on a SOAP engines like the Cape Clear or Axis. These ‘Service References’ are providing the interoperability between the WebService and Dynamics Ax 2009 as consumer (see ‘consume a WebService from X++’ and the whitepaper). There are some comatibility limitations known:

1. No support for SOAP headers
   
2. Client-code must be executed on the server (AOS)
   
3. Limited authentication support (you cannot authenticate with a different user account) due the missing impersonation support on the AOS
   
4. Service references only support Wsdl with only one service group
   
5. Only services with Document/literal binding style

You can workaround these limitations (Points 1-4) by creating manually the WebService-proxy as it was necessary with Dynamics 4 with the wsdl.exe tool.

Regarding point 5, the workaround can be writing a custom WebService proxy or to ask the WebService provider to expose his service with Document/literal style. WebService-Server such as Axis do support both types, so it might be possible to change the configuration on the server side. The article from Russell Butek describes and compares the possible choices.

If it is not possible to change the binding-style (for example if the service is using overloaded methods or if the provider refuses is), the only possible workaround is to create manually the WebService-proxy then to decorate the WebMethod with the SoapRpcMethod-Attribute and to reference this assembly as it was done for Dynamics Ax4. This because neither the asmx.exe tool (ASP.Net-WebServices), nor the svcutil.exe (WCF-Services) do support the RPC-binding-style.

A great source of knowledge about the interoperability between .Net and WebSphere is the IBM Redbook (WebSphere and .Net Interoperability Using Web Services) and the msdn article about customizing SOAP Formatting.