Some months ago, I was asked for an intervention regarding a SSL client certificate issue. There was a problem related to the setup of transport security (SSL) of a WCF service hosted in IIS 7.0, using client certificates that are mapped to a local account.  Let’s have a look.

The Setup

Server Setup

• Wild card server certificate is installed in IIS (server level). Wild card is required, because we’re using multiple host names are configured.

• The Certificate Authority is added to the Trusted Root Certification Authorities store (Local Machine)

• Website binding is configured to use https with the server certificate for SSL

• Website is configured to require SSL and to require client certificates

• Client certificate mapping is configured in order to map an individual client certificate to a specific Windows account. Configurable via this extension.

      

 

       This extension actually changes this configuration:

• An Allow authorization rule is configured for this Windows account

• Anonymous Authentication is enabled (Client Certificate is anonymous authentication)

• WCF service is configured for transport security

Client Setup

• The Certificate Authority is added to the Trusted Root Certification Authorities store (Local Machine)

• Client Certificate (containing private key) is added to the Personal certificate store (Local Machine).  This is required for the WCF client

• Client Certificate (containing private key) is added to the Personal certificate store (Current User).  This is required for browsing to the service via IE

• WCF Client is configured for transport security, providing Client Certificates:

Problem Solving

The issue

When browsing to the service, for a particular web server, we’re not prompted to select a client certificate. Instead, we get this exception:

The page you are attempting to access requires your browser to have a Secure Sockets Layer (SSL) client certificate that the Web Server recognizes.

Troubleshooting

We configured another web server with exactly the same setup, which worked fine.  But still it didn’t work on that particular web server. Handy tools / commands during troubleshooting:

• netsh http show sslcert
• SSL Diagnostics

At the end, a warning in the System Event Log gave the solution. This entry is only written to the Event Log for the first call after the IIS service is restarted. That’s why we didn’t discover this Event Log warning earlier.

When asking for client authentication, this server sends a list of trusted certificate authorities to the client.  The client uses this list to choose a client certificate that is trusted by the server.  Currently, this server trusts so many certificate authorities that the list has grown too long.  This list has thus been truncated.

Root cause

During the handshake protocol for client certificate authorization, the server sends a list of Trusted Root Certification Authorities to the client.  The client will in this case only provide Client Certificates, issued by one of these Trusted Root Certification Authorities.  The problem was that the Trusted Root Certification Authorities list was too long on that particular server, so it was truncated before sent to the client.  Unluckily, our Root Certificate Authority was truncated from the list, so the handshake failed.

Solutions

There are two solutions to solve this issue:

• The first solution is to clean up the Trusted Root Certification Authorities store (Local Machine) and remove all unnecessary certificates. Be aware that you don’t remove certificates that are required by Windows.

• A second solution is to configure Schannel to no longer send the list of trusted root certification authorities during the TLS/SSL handshake process.  This can be done by adding this registry entry on the web server:

        HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL

        Value name: SendTrustedIssuerList
        Value type: REG_DWORD
        Value data: 0 (False)

Result

When browsing to the service, we’re now promoted for our Client Certificate. Now we can access the service:

BizTalk provides out-of-the-box functionality to include your custom BizTalk database in the standard backup procedure. 
You can find all details on MSDN.  Here’s a small synopsis:

• Execute these scripts against your custom database
  • %BTSINTALLDIR%\Schema\Backup_Setup_All_Procs.dsl
  • %BTSINTALLDIR%\Schema\Backup_Setup_All_Tables.dsl

• Add the SQL Agent account to the BTS_BACKUP_USERS role of your custom database

• Modify the adm_OtherBackupDatabases table of the BizTalkMgmtDb, add a record for your custom database

       

 

However, when I executed the BizTalk Backup Job after this change, I got the following exception:

• [SQLSTATE 01000] (Message 4035)  BACKUP LOG is terminating abnormally. [SQLSTATE 42000] (Error 3013)  BACKUP LOG cannot be performed because there is no current database backup.

The cause was the fact that it is not possible to take a transactional backup of a database, if you didn’t take a full backup first.  This issue was fixed by executing the stored procedure sp_ForceFullBackup of the BizTalkMgmtDb.  Now the custom database had a initial full backup and the BizTalk Backup Job executed successfully.  This result was an extra database backup:

In many scenarios, it could be required to have a send port with a dynamic behavior:

• Send messages to a FILE location, containing the date of today
• Send a notification mail to many different recipients
• Dynamically change the URL of the backend web service, depending on the incoming request
• …

Many developers would solve this by using dynamic send ports.  These ports allow you to configure all adapter properties, even the adapter type, at runtime.  I’m not a big fan of dynamic send ports, because it introduces some drawbacks:

• Dynamic send ports are very difficult to troubleshoot (a hell for your operations team)
• Dynamic send ports require your port configuration to be stored in a secure way (custom SSO application)
• Dynamic send ports have a bigger performance hit (solved in BTS 2013)
• Dynamic send ports don’t allow to specify an adapter handler (solved in BTS 2013)

That’s why I prefer using static send ports.  With a very easy trick, you can make static send ports partially dynamic.  Mostly it’s only the connectionstring, URI, path that must be changed at runtime.  This can be achieved in a custom pipeline component in the send pipeline:

• inmsg.Context.Promote("OutboundTransportLocation", "http://schemas.microsoft.com/BizTalk/2003/system-properties", URL);

This dynamic behavior works smooth for FILE and FTP adapters.  However, when using this mechanism on WCF send ports, there’s a caveat.  You will find out that the BTS.OutboundTransportLocation of the first message will be cached on the WCF send port.  So all subsequent messages will be sent to the same location.  This port configuration is cached until your send port configuration is modified or until your adapter send handler is restarted.  Luckily: there’s a way to disable this caching:

• inmsg.Context.Promote("IsDynamicSend", "http://schemas.microsoft.com/BizTalk/2003/system-properties", true);
• inmsg.Context.Promote("OutboundTransportLocation", "http://schemas.microsoft.com/BizTalk/2003/system-properties", URL);

By setting the BTS.IsDynamicSend property to true, you force the WCF send adapter not to use the cache, but the runtime value instead.  More information on this setting can be found on MSDN.

The BizTalk Server 2013 Beta release comes with the SB-Messaging adapter.  This adapter allows our on-premise BizTalk environment to integrate seamlessly with the Windows Azure Service Bus queues, topics and subscriptions.  Together with my colleague Mathieu, I had a look at these new capabilities.

Adapter Configuration

The configuration of SB-Messaging receive and send ports is really straightforward.  BizTalk just needs these properties in order to establish a connection to the Azure cloud:

• Service Bus URL of the queue, topic or subscription:

        sb://<namespace>.servicebus.windows.net/<queue_name>

• Access Control Service STS URI:

        https://<namespace>-sb.accesscontrol.windows.net/

• Issuer name and key for the Service Bus Namespace

Content Based Routing

Both Service Bus and BizTalk messaging layer offer a publish-subscribe engine, which allows for content based routing.  In BizTalk, content based routing is done through context properties, the Azure Service Bus uses Brokered Message properties.  A BizTalk context property is a combination of the propertyName and propertyNamespace.  In Azure Service Bus, context properties are only defined by a propertyName.  How are these metadata properties passed from the cloud to BizTalk and vice versa?

Sending from BizTalk to Service Bus topic

In order to pass context properties to the Service Bus topic, there’s the capability to provide the Namespace for the user defined Brokered Message Properties.  The SB-Messaging send adapter will add all BizTalk context properties from this propertyNamespace as properties to the Brokered Message.  Thereby, white space is ignored.

Receiving from Service Bus subscription to BizTalk

Also at the receive adapter, there’s the possibility to pass properties to the BizTalk message context.  You can specify the Namespace for Brokered Message Properties, so the SB-Messaging adapter will write (not promote) all Brokered Message properties to the BizTalk message context, within the specified propertyNamespace.  Be aware when checking the option Promote Brokered Message Properties, because this requires that a propertySchema is deployed which contains all Brokered Message properties.

Receive Port Message Handling

I was interested in the error handling when an error occurs in the receive adapter or pipeline.  Will the message be roll backed to the Azure subscription or suspended in BizTalk?  Two fault scenarios were investigated.

Receive adapter unable to promote property in BizTalk context

In this case, we configured the receive port to promote the context properties to a propertyNamespace that did not contain all properties of the Brokered Message.  As expected, the BizTalk adapter threw an exception:

• The adapter "SB-Messaging" raised an error message. Details "System.Exception: Loading property information list by namespace failed or property not found in the list. Verify that the schema is deployed properly.
  

The adapter retried 10 times in total and moved afterwards the Brokered Message to the dead letter queue of the Service Bus subscription.  Afterwards, BizTalk started processing the next message.

Receive pipeline unable to parse message body

In this simulation we tried to receive an invalid XML message with the XMLReceive pipeline.  After the error occurred, we discovered that the message was suspended (persisted) in BizTalk.

WCF-Adapter Framework

It’s a pity to see that this new adapter is not implemented as a WCF-binding.  Due to this limitation, we can’t make use of the great extensibility capabilities of the WCF-Custom adapter.  The NetMessagingBinding could be used, but I assume some extensibility will be required in order to transform BizTalk context properties into BrokeredMessageProperty objects and vice versa.  Worthwhile investigating…

Conclusion

The BizTalk product team did a great job with the introduction of the SB-Messaging adapter!  It creates a lot of new opportunities for hybrid applications.

Lately I came across a weird exception while building a BizTalk project with Team Foundation Server.  Let’s have a look.

The error

Although the build succeeded locally, we got this error while building our BizTalk project with TFS:

FlatFileSchema.xsd.cs: The type or namespace name '<ContextPropertyName>' could not be found in the global namespace (are you missing an assembly reference?)

The troubleshooting

After some try/error, we discovered that the error only occurred when building a BizTalk project in TFS that contains a flat file schema, using property promotion.   The first reflex was to compare the installed software on our local development machine and the Team Foundation Server.

• Local machine: Full BizTalk 2010 Installation
• TFS server: BizTalk 2010 Build Component

The solution

The solution was to install also the Developer Tools and SDK on the TFS server.  Although MSDN states that the Build Component should be sufficient.  This extra installation adds “Developer Tools\Schema Editor Extensions” to the BizTalk folder.  This is apparently needed for building flat files schemas that use property promotion.

In more advanced WCF scenarios, the BizTalk standard functionality can be insufficient.  In those cases, WCF extensibility can help us to overcome the limitations of the standard BizTalk WCF adapters.  Typical examples are custom MessageInspectors, ErrorHandlers, Decoders and AuthorizationBehaviors.

Once you have registered the extensibility, you can configure it on the WCF-Custom or WCF-CustomIsolated receive and send ports:

When the WCF send or receive port is executed, your WCF extensibility objects will be injected into the WCF channel stack.

But how can we register these WCF extensions?

BizTalk 2006 R2 and BizTalk 2010

In the previous versions of BizTalk, there was only one way to register WCF extensions: the machine.config.

-   The C:\Windows\Microsoft.NET\Framework\v2.0.50727\CONFIG\machine.config is needed for 32-bit processes:

• BizTalk 32-bit host instances
• IIS 32-bit applications
• BizTalk Administration Console

-   The C:\Windows\Microsoft.NET\Framework64\v2.0.50727\CONFIG\machine.config is needed for 64-bit processes

• BizTalk 64-bit host instances
• IIS 64-bit applications

BizTalk 2010: The new feature

BizTalk Server 2010 comes with a nice new feature for registering your WCF extensibility assemblies. The new feature allows you to avoid the machine.config and to register them in BizTalk itself. Let’s have a look!

• Browse to the WCF-Custom adapter handlers.

       

 

• Open the receive or send handler.  Choose Properties.

 

       

• Here you can import a web.config / app.config that contains your WCF extensions.

BizTalk 2010: The caveat

Unfortunately, this doesn’t work if your receive port is hosted in IIS.  You can register the WCF extensions on the WCF-CustomIsolated adapter handlers. However, when the WCF-CustomIsolated receive port is called, you get an activation error:

“WebHost failed to process a request.

Sender Information: System.ServiceModel.ServiceHostingEnvironment+HostingManager/45653674

Exception: System.ServiceModel.ServiceActivationException: The service '/ApplicationName/Service.svc' cannot be activated due to an exception during compilation. The exception message is: Unable to create endpoint behavior configuration element from XML configuration.

Check the following:

1. Verify behavior element extensions in machine.config are correctly configured.
2. Restart the application if machine.config was recently updated.
3. Ensure the configuration is valid XML that conforms to the configuration schema.”

Adding the WCF extensions in the corresponding web.config of IIS also doesn’t solve this issue.  The only solution I’ve found is to register them again in the machine.config.  Remember that BizTalk 2010 is .NET 4.0.

- The C:\Windows\Microsoft.NET\Framework\v4.0.30319\CONFIG\machine.config is needed for 32-bit processes:

• BizTalk 32-bit host instances
• IIS 32-bit applications
• BizTalk Administration Console

- The C:\Windows\Microsoft.NET\Framework64\v4.0.30319\CONFIG\machine.config is needed for 64-bit processes

• BizTalk 64-bit host instances
• IIS 64-bit applications

Conclusion

-   Only when using the WCF-Custom adapter in BizTalk 2010, you can register WCF extensions in BizTalk itself.

-   In all other scenarios, you need to register them in the corresponding machine.config.  This has the drawback that this also influences other applications on the server.

Please get in touch if you managed to get this working!

Today I’ve encountered an issue with remote BizTalk deployment.  Every night we run a TFS build and the result of that build is deployed to our BizTalk Test Server.  Because the build process runs on our TFS Build Server, we actually perform a remote deployment to the BizTalk Test Server.  Until last night, everything worked fine.

The error

This error occurred during the import of one of the binding files: Failed to create 'WCF-Custom' Transport Component.

The reason

It was the first time we tried to remotely import a BizTalk binding file that contained the WCF-Custom adapter.

The troubleshooting

I used the Microsoft.BizTalk.Deployment.DeployerComponent to import the bindings.  I created a workaround for the issue, by executing BTSTASK.exe remotely via PSEXEC.exe.  This worked fine, but then I’ve got the same error while starting receive locations and send ports, that were configured with the WCF-Custom adapter.  As I didn’t have a good command line alternative for this functionality, the workaround was useless.

Afterwards, I’ve tried to install some extra BizTalk software on the TFS Build Server. And yes, this was the way to go!

The solution

The Windows Communication Foundation Adapter runtime should also be installed on the local machine (in our case TFS Build Server).  This is not documented somewhere and it’s not the behavior you would expect.  The BizTalk deployment libraries work fine for remote deployment, until you use the WCF adapter…

This is an overview of the BizTalk software installed on our TFS Build Server:

- BizTalk Developer Tools and SDK  [needed to run Unit Tests]

- BizTalk Project Build Component  [needed to build BizTalk Projects]

- BizTalk 2010 Cumulative Update Pack 4.0 [contains this fix]

- Windows Communication Foundation Adapter [apparently needed to remotely import bindings containing WCF adapters]

It’s a good practice to have some XML validation in your BizTalk integration flows.  It prevents you of sending mal-formatted messages to back-end systems and it also gives you the opportunity to validate incoming messages.  In the BizTalk toolbox, you have two standard pipeline components that can perform this XML validation.  Let’s have a look...

XML Disassembler (or XML Assembler)

The default configuration of the XML Disassembler will not perform any kind of XML validation on the message

If you want to enable XML validation on the XML Disassembler you need to set Validate document structure to True and explicitly set the Document schema(s) that need to be validated. Compared to the specified Documents schema(s):
- If the processed message has the same TargetNamespace#RootNodeName combination, XML validation will be performed

- If the processed message has another TargetNamespace#RootNodeName combination, an exception will be thrown (can’t recognize the data)

XML Validator

The default configuration of the XML Validator will already perform XML validation. How? It retrieves the XML definition from the BizTalkMgmtDb, at run-time, using the TargetNamespace#RootNodeName combination.

-   If a matching schema is found, XML validation will be performed on the processed message

-   If no matching schema is found, the XML Validator will throw an exception (cannot retrieve document specification)

You can also explicitly specify at design-time the Document schema(s).  Compared to the specified Documents schema(s):

-   If the processed message has the same TargetNamespace#RootNodeName combination, XML validation will be performed

-   If the processed message has another TargetNamespace#RootNodeName combination, no XML validation will be performed

Conclusion

You see a different behavior when comparing the components, especially when specifying Document schema(s). Depending on your needs, you can choose the appropriate setup.  I mostly opt for the combination of the XML Disassembler and XML Validator, both with their default configuration.  It has the advantage that you don’t need to configure anything at design-time.  They work together in this way:

-   The XML Disassembler is responsible for retrieving the BTS.MessageType, promoting context properties and debatching

-   The XML Validator will validate all messages, deciding at run-time which schema to use

It’s a common practice to reuse schemas / types within your BizTalk solution.  Lately, I’ve encountered an issue regarding this.  Here you can find a simplified example and a solution to the problem.

Assume you have two reusable schemas (no dependencies between them):

-   http://schemas.codit.eu/common#Address

-   http://schemas.codit.eu/common#ContactInformation

Now you want to create a “Person’ schema in the http://schemas.codit.eu namespace, by reusing the previous schemas.

-   First you need to import the Address schema

-   Secondly you need to import also the ContactInformation schema.  This results in the error:

 
 The namespace of the schema you are trying to add clashes with one of the namespaces already declared.  Please choose another schema.

Although, in XSD this is not a limitation.  So I’ve tried to work around the BizTalk Schema Editor and opened the XSD as an XML file.  I’ve manually added the XSD import of the ContractInformation schema:

After this workaround, I’ve opened the schema again with the BizTalk Schema Editor, without any errors.  It just seems to be a limitation of the BizTalk Schema Editor.

As you all know, the BizTalk XML Disassembler checks - by default - if a schema is deployed that matches the incoming message.  BizTalk does this via the BTS.MessageType, which is a combination of TargetNamespace#RootNode.  This BTS.MessageType must be unique in your BizTalk Group.  If two schemas are deployed with the same TargetNamespace#RootNode, the XML Disassembler will throw this error message:

• Cannot locate document specification because multiple schemas matched the message type

Lately we had an issue, related to this subject.  We had two schemas deployed, that varied only by case.  Below, you find a similar example.

Now the question is: will BizTalk treat these schemas as identical schemas or not? My first guess was that BizTalk would treat these schemas as unique because it’s related to XML, which is case-sensitive.  However, when processing one of the two messages, the XML Disassembler threw an error because multiple schemas matched the message type.

I investigated how BizTalk resolved the schema, so I turned on SQL Server Profiler.  There, I discovered this entry:

• exec bt_GetDocSpecInfoByMsgType @nvcMsgtype=N'http://Codit.BizTalk.Blog.REQUEST#REQUEST',@iPipelineAssemblyId=2,@iFlag=@p3

The most important query of the GetDocSpecInfoByMsgType stored procedure is this one:

Because my SQL Server Collation, Latin1_General_CI_AS, is case-insensitive, the query results into 2 matched schemas, so the XML Disassembler will throw an exception.

After some searching on MSDN I’ve found this remark:

• If you will be using two namespaces that vary only by case, the BizTalk database must be installed with a case-sensitive collation. Examples of case-sensitive collations include binary and non-binary collations with case-sensitivity enabled. If this is not done, schema resolution will fail because XML is case-sensitive.

Conclusion: Is the BTS.MessageType case-sensitive or case-insensitive? It depends on your SQL Server Collation.

Toon Vanhoutte