Troubleshooting Certificates
Microsoft BizTalk Server can make use of public key infrastructure (PKI) digital certificates for purposes of document encryption and decryption, document signing and verification (non-repudiation) and for party resolution. This topic describes various certification usage scenarios and configuration options and provides some general guidelines for using digital certificates with BizTalk Server.
Certificate Usage Scenarios and Configuration Options
Most problems that occur while using certificates with BizTalk Server are a result of incorrect or incomplete configuration. For example importing the correct certificate into the wrong certificate store, the incorrect certificate into the correct store, or failure to enter the appropriate information into the BizTalk Administration console will cause run-time errors to occur when using certificates.
Use the following table as a reference for the certificate usage scenarios and configuration options available in BizTalk Server:
| Certificate Usage | User Context | Certificate Store Location | Certificate Type | Pipeline Component Used | Configuration Parameters in the BizTalk Server Administration Console |
|---|---|---|---|---|---|
| Encryption (Sending) | Account used by the host instance associated with the send handler | Log on to each computer running BizTalk Server that will host S/MIME encoder pipelines and import the encryption certificate into the Local Computer \ Other People store. | Trading partner public certificate | MIME/SMIME encoder | - Specify values for the encryption certificate Common Name and Thumbprint on the Certificate page of the Send Port Properties dialog box. - Specify pipeline Encode options in the Configure Pipeline dialog box. The Configure Pipeline dialog box is displayed by clicking the button next to the Send pipeline drop-down list on the General page of the Send Port Properties dialog box. |
| Decryption (Receiving) | Account used by the host instance associated with the receive handler | Log on to each computer running BizTalk Server that will host S/MIME decoder pipelines as each host instance service account, and import the decryption certificate to the Current User \ Personal store. Note: For pipeline decryption to succeed on an IIS 7.0 computer, ensure that the account for the IIS application pool and the account used by the host instance associated with the receive handler are the same and that this account is a member of the <machineName>\IIS_WPG group. For more information about setting IIS process identity for IIS 7.0, see Guidelines for Resolving IIS Permissions Problems. These processes must run under the same account to ensure that the account profile is loaded which in turns loads the registry keys required to perform decryption in the pipeline. For performance reasons, IIS 6.0 does not load the account profile when starting the associated w3wp.exe process so the BizTalk Server host instance must be configured with the same account so that BizTalk Server will load the account profile and registry keys. | Own private certificate | MIME/SMIME decoder | - Specify values for the decryption certificate Common Name and Thumbprint on the Certificates page of each Host Properties dialog box. - Specify pipeline Decode options in the Configure Pipeline dialog box. The Configure Pipeline dialog box is displayed by clicking the button next to the Receive pipeline drop-down list on the General page of the Receive Location Properties dialog box. |
| Signature (Sending) | Account used by the host instance associated with the send handler | Log on to each computer running BizTalk Server that will host S/MIME encoder pipelines as each host instance service account, and import the signature certificate to the Current User \ Personal store. | Own private certificate | MIME/SMIME encoder | - Specify values for the signature certificate Common Name and Thumbprint on the Certificate page of the BizTalk Group Properties dialog box. Note: Only one signature certificate can be specified per each BizTalk Server group. - Specify pipeline Encode options in the Configure Pipeline dialog box. The Configure Pipeline dialog box is displayed by clicking the button next to the Send pipeline drop-down list on the General page of the Send Port Properties dialog box. |
| Signature Verification (Receiving) | Account used by the host instance associated with the receive handler | Log on to each computer running BizTalk Server that will host S/MIME decoder pipelines and import the signature certificate to the Local Computer \ Other People store. | Trading partner public certificate | MIME/SMIME decoder | - Specify values for the verification certificate Common Name and Thumbprint on the Certificates page of each Party Properties dialog box. - Specify pipeline Decode options in the Configure Pipeline dialog box. The Configure Pipeline dialog box is displayed by clicking the button next to the Receive pipeline drop-down list on the General page of the Receive Location Properties dialog box. Note: Configuration of the Decode option requires that a pipeline with the MIME/SMIME decoder component is deployed. |
| Party Resolution (Receiving) | Account used by the host instance associated with the receive handler | Log on to the BizTalk Server computer from which party resolution is being configured, and import the certificate into the Local Computer \ Other People store. | Trading partner public certificate | Party resolution | - Specify values for the certificate Common Name and Thumbprint on the Certificates page of each Host Properties dialog box. - Specify ResolveParty options in the Configure Pipeline dialog box. The Configure Pipeline dialog box is displayed by clicking the button next to the Receive pipeline drop-down list on the General page of the Receive Location Properties dialog box. Note: Configuration of this option requires the use of a pipeline that contains the Party resolution component. The XMLReceive pipeline contains the Party resolution component. |
| HTTPS (Sending) | Account used by the host instance associated with the send handler | SSL communication does not require a client certificate. Whether a client certificate is required is at the discretion of the destination Web server administrator. If the destination Web server requires a client certificate then follow these steps: - Obtain the public certificate from the trading partner. - Log on to each computer running BizTalk Server as the account used by the host instance associated with the send handler. - Import the certificate into the Current User \ Personal store. For information about how to obtain a certificate using Windows Server 2008 Certificate Services Web pages, see Request a Certificate Over the Web. |
Trading partner public certificate | NA | - HTTP Transport - Set the SSL client certificate thumbprint option on the Authentication tab of the HTTP Transport Properties dialog box. The HTTP Transport Properties dialog box is displayed by clicking the Configure button on the General page of the Send Port Properties dialog box. - SOAP Transport - Set the Client certificate thumbprint option on the General tab of the SOAP Transport Properties dialog box. The SOAP Transport Properties dialog box is displayed by clicking the Configure button on the General page of the Send Port Properties dialog box. |
To display the Certificates Management Console interface for Local Computer and Current User
Click Start, click Run, type MMC, and click OK to open the Microsoft Management Console.
Click the File menu, and then click Add/Remove Snap-in to display the Add/Remove Snap-in dialog box.
Select Certificates from the list of available snap-ins and click Add.
Select Computer account, click Next, and then click Finish. This will add the Certificates Management Console interface for Local Computer.
Ensure that Certificates is still selected from the list of snap-ins, and then click Add again.
Select My user account and then click Finish. This will add the Certificates Management Console interface for Current User.
Note
This displays the Certificates Management Console for the account that you are currently logged on as. If you need to import certificates into the Personal store for a service account then you should log on with the service account credentials first.
Click the OK button on the Add/Remove Snap-in dialog box.
General Guidelines
Ensure that the imported certificate is being used for its intended purpose: To do this, double-click the certificate in the Certificates Management Console interface and then click the Details tab of the Certificate dialog box. Then click the All option for the Show drop-down list and then click to select the Key Usage and/or Enhanced Key Usage fields to verify the intended purpose. If BizTalk Server attempts to use a certificate for other than its intended purpose a runtime error will occur.
Test your connection to the target Web site: If you are using SSL, ensure that you can connect to the target Web site with Internet Explorer before attempting to connect to the target Web site with the HTTP or SOAP transports. Verify that no dialog boxes are displayed in Internet Explorer when you connect to the target Web site. BizTalk Server has no mechanism for interfacing with any dialog boxes that might be displayed when connecting to the target web site. A dialog box may be displayed by Internet Explorer if the target web site name does not match the name specified for the web site in the SSL certificate or if the Root Certificate Authority for the SSL certificate is not in the appropriate Trusted Root Certification Authorities store.
Use the SSL Diagnostics tool to analyze SSL connection issues: The SSL Diagnostics tool is an optional component of the IIS Diagnostics Toolkit. For more information, see IIS Diagnostics Tools.
Ensure that the certificate is valid. BizTalk Server does not prompt you if the certificate has expired. Instead, BizTalk Server will suspend the message.
See Also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for