Upraviť

Zdieľať cez

Connect to an IBM MQ server from a workflow in Azure Logic Apps

  • Článok

Applies to: Azure Logic Apps (Consumption + Standard)

This article shows how to access an Azure-hosted or on-premises MQ server from a workflow in Azure Logic Apps using the MQ connector. You can then create automated workflows that receive and send messages stored in your MQ server. For example, your workflow can browse for a single message in a queue and then run other actions.

The MQ connector provides a wrapper around a Microsoft MQ client, which includes all the messaging capabilities to communicate with a remote MQ server across a TCP/IP network. This connector defines the connections, operations, and parameters to call the MQ client.

Supported IBM WebSphere MQ versions

  • MQ 7.5
  • MQ 8.0
  • MQ 9.0, 9.1, 9.2, and 9.3

Connector technical reference

The MQ connector has different versions, based on logic app type and host environment.

Logic app Environment Connection version
Consumption Multitenant Azure Logic Apps Managed connector, which appears in the connector gallery under the Runtime > Shared. This connector provides only actions, not triggers. In on-premises MQ server scenarios, the managed connector supports server only authentication with TLS (SSL) encryption.

For more information, review the following documentation:

- MQ managed connector reference
- Managed connectors in Azure Logic Apps
Standard Single-tenant Azure Logic Apps and App Service Environment v3 (ASE v3 with Windows plans only) Managed connector, which appears in the connector gallery under Runtime > Shared, and built-in connector, which appears in the connector gallery under Runtime > In-App and is service provider-based. The built-in version differs in the following ways:

- The built-in version includes actions and triggers.

- The built-in connector can directly connect to an MQ server and access Azure virtual networks by using a connection string without an on-premises data gateway.

- The built-in version supports both server authentication and server-client authentication with TLS (SSL) encryption for data in transit, message encoding for both the send and receive operations, and Azure virtual network integration.

For more information, review the following documentation:

- MQ managed connector reference
- MQ built-in connector reference
- Built-in connectors in Azure Logic Apps

Authentication with TLS (SSL) encryption

Based on whether you use the MQ managed connector (Consumption or Standard workflows) or the MQ built-in connector (Standard workflows only), the MQ connector supports one or both of the following authentication directions:

Authentication Supported logic app type and MQ connector Process
Server only
(one-way)		 - Consumption: Managed only

- Standard: Managed or built-in		 For server authentication, your MQ server sends a private key certificate, either publicly trusted or non-publicly trusted, to your logic app client for validation. The MQ connector validates the incoming server certificate for authenticity against public key certificates, known also as a "signer" certificates, by using standard .NET SSL stream validation.

The logic app doesn't send a client certificate.
Server-client
(two-way)		 - Consumption: Not supported

- Standard: Built-in only		 For server authentication, see the previous row.

For client authentication, the logic app client sends a private key certificate to your MQ server for validation. The MQ server validates the incoming client certificate for authenticity also by using a public key certificate.

Notes about private key and public key certificates

  • The certificate that requires validation is always a private key certificate. The certificate used to perform the validation is always a public key certificate.

  • A publicly trusted private key certificate is issued by a recognized Certificate Authority. A non-publicly trusted private key certificate includes self-signed, private CA, and similar certificates.

  • To validate a private key certificate sent from your MQ server, the MQ connector uses public key certificates that usually exist on your logic app's virtual machine host in the host's Trusted Root Certification Authorities (CA) Store.

    However, if the host doesn't have all the required public key certificates, or if your MQ server sends a non-publicly trusted private key certificate, you need to take extra steps. For more information, see Prerequisites.

  • To validate a client's private key certificate sent from your Standard logic app, the MQ server uses public key certificates that exist in your MQ server's certificate store. To add a private key certificate for your logic app to use as a client certificate, see Add a private key certificate.

Limitations

  • Authentication with TLS (SSL) encryption

    MQ connector Supported authentication direction
    Managed Server only (one-way)
    Built-in - Server-client (two-way)
    - Server-only (one-way)

  • Server certificate validation

    The MQ built-in connector doesn't validate the server certificate's expiration date nor certificate chain.

  • Character set conversions

    • The MQ managed connector doesn't make any character set conversions nor use the message's Format field. The connector only copies whatever data appears in the message field and sends the message along.

    • The MQ built-in connector can make character set conversions, but only when the data format is a string. If you supply a different character set ID (code page), the connector attempts to convert the data to the new code page.

  • The MQ connector doesn't support segmented messages.

For more information, review the MQ managed connector reference or the MQ built-in connector reference.

Prerequisites

  • Cipher specification requirements

    The MQ server requires that you define the cipher specification for connections that use TLS (SSL) encryption. This cipher specification must match the cipher suites that are supported, chosen, and used by the operating system where the MQ server runs. Ultimately, the cipher specification used by the client connection must match the cipher suites set up on the server-connection channel on the MQ server.

    For more information, see Connection and authentication problems.

Add an MQ trigger (Standard logic app only)

The following steps apply only to Standard logic app workflows, which can use triggers provided by the MQ built-in connector. The MQ managed connector doesn't include any triggers.

These steps use the Azure portal, but with the appropriate Azure Logic Apps extension, you can also use Visual Studio Code to create a Standard logic app workflow.

  1. In the Azure portal, open your blank logic app workflow in the designer.

  2. Follow these general steps to add the MQ built-in trigger that you want. For more information, see MQ built-in connector triggers.

  3. Provide the required information to authenticate your connection. When you're done, select Create.

  4. When the trigger information box appears, provide the required information for your trigger.

  5. When you're done, save your workflow. On the designer toolbar, select Save.

Add an MQ action

A Consumption logic app workflow can use only the MQ managed connector. However, a Standard logic app workflow can use the MQ managed connector and the MQ built-in connector. Each version has multiple actions. For example, both managed and built-in connector versions have their own actions to browse a message.

  • Managed connector actions: These actions run in a Consumption or Standard logic app workflow.

  • Built-in connector actions: These actions run only in a Standard logic app workflow.

The following steps use the Azure portal, but with the appropriate Azure Logic Apps extension, you can also use the following tools to create logic app workflows:

  1. In the Azure portal, open your logic app workflow in the designer.

  2. Follow these general steps to add the MQ action that you want. For more information, see MQ connector actions.

  3. Provide the required information to authenticate your connection. When you're done, select Create.

  4. When the action information box appears, provide the required information for your action.

  5. When you're done, save your workflow. On the designer toolbar, select Save.

Test your workflow

To check that your workflow returns the results that you expect, run your workflow, and then review the outputs from your workflow's run history.

  1. Run your workflow.

    • Consumption logic app: On the workflow designer toolbar, select Run Trigger > Run.

    • Standard logic app: On workflow resource menu, select Overview. On the Overview pane toolbar, select Run Trigger > Run.

    After the run finishes, the designer shows the workflow's run history along with the status for each step.

  2. To review the inputs and outputs for each step that ran (not skipped), expand or select the step.

    • To review more input details, select Show raw inputs.

    • To review more output details, select Show raw outputs. If you set IncludeInfo to true, more output is included.

View and add certificates for authentication with TLS (SSL) encryption

The following information applies only to Standard logic app workflows for the MQ built-in connector using either server-only or server-client authentication with TLS (SSL) encryption.

View and confirm thumbprints for existing public key certificates

To check that the thumbprints for the required public key certificates exist on your Standard logic app's virtual machine host in the Trusted Root CA Store, follow these steps to run the cert PowerShell script from your Standard logic app's resource menu.

  1. In the Azure portal, open your Standard logic app resource. On the logic app resource menu, under Development Tools, select Advanced Tools > Go.

  2. From the Kudu Debug console menu, select PowerShell.

  3. After the PowerShell window appears, from the PowerShell command prompt, run the following script:

    dir cert:\localmachine\root

    The PowerShell window lists the existing thumbprints and descriptions, for example:

    Screenshot showing existing example thumbprints and descriptions.

Add a public key certificate

To add a public key certificate to the Trusted Root CA Store on that virtual machine host where your Standard logic app runs, follow these steps:

  1. In the Azure portal, open your Standard logic app resource. On the logic app resource menu, under Settings, select TLS/SSL settings (classic).

  2. On the TLS/SSL settings (classic) page, select the Public Key Certificates (.cer) tab, and then select Upload Public Key Certificate.

  3. On the Add Public Key Certificate (.cer) pane that opens, enter a name to describe the certificate. Find and select the public key certificate file (.cer). When you're done, select Upload.

  4. After you add the certificate, from the Thumbprint column, copy the certificate's thumbprint value.

    Screenshot showing the Azure portal and Standard logic resource with the following items selected: 'TLS/SSL settings (classic)', 'Public Key Certificates (.cer)', and 'Upload Public Key Certificate'.

  5. On the logic app resource menu, select Configuration.

  6. On the Application settings tab, select New application setting. Add a new application setting named WEBSITE_LOAD_ROOT_CERTIFICATES, and enter the certificate's thumbprint value that you previously copied. If you have multiple certificate thumbprint values, make sure to separate each value with a comma (,).

    For more information, see Edit host and app settings for Standard logic apps in single-tenant Azure Logic Apps.

    Note

    If you specify a thumbprint for a private CA certificate, the MQ built-in connector doesn't run any certificate validation, such as checking the certificate's expiration date or source. If standard .NET SSL validation fails, the connector only compares any thumbprint value that's passed in against the value in the WEBSITE_LOAD_ROOT_CERTIFICATES setting.

  7. If the added certificate doesn't appear in the public key certificates list, on the toolbar, select Refresh.

Add a private key certificate

To add a private key certificate to the Trusted Root CA Store on virtual machine host where your Standard logic app runs, follow these steps:

  1. In the Azure portal, open your logic app resource. On the logic app resource menu, under Settings, select TLS/SSL settings (classic).

  2. On the TLS/SSL settings (classic) page, select the Private Key Certificates (.pfx) tab, and then select Upload Certificate.

  3. On the Add Private Key Certificate (.pfx) pane that opens, find and select the private key certificate file (.pfx), and then enter the certificate password. When you're done, select Upload.

  4. After you add the certificate, from the Thumbprint column, copy the certificate's thumbprint value.

    Screenshot showing the Azure portal and Standard logic resource with the following items selected: 'TLS/SSL settings (classic)', 'Private Key Certificates (.pfx)', and 'Upload Certificate'.

  5. On the logic app resource menu, select Configuration.

  6. On the Application settings tab, select New application setting. Add a new application setting named WEBSITE_LOAD_CERTIFICATES, and enter the certificate's thumbprint value that you previously copied.

    For more information, see Edit host and app settings for Standard logic apps in single-tenant Azure Logic Apps.

  7. If the added certificate doesn't appear in the private key certificates list, on the toolbar, select Refresh.

  8. When you create a connection using the MQ built-in connector, in the connection information box, select Use TLS.

  9. In the Client Cert Thumbprint property, enter the previously copied thumbprint value for the private key certificate, which enables server-client (two-way) authentication. If you don't enter a thumbprint value, the connector uses server-only (one-way) authentication.

    Screenshot showing Standard logic app workflow designer, MQ built-in connection box with 'Use TLS' option selected and the 'Client Cert Thumbprint' property with private key certificate thumbprint entered.

Troubleshoot problems

Failures with browse or receive actions

If you run a browse or receive action on an empty queue, the action fails with the following header outputs:

Screenshot showing the MQ "no message" error.

Connection and authentication problems

When your workflow uses the MQ managed connector to connect to your on-premises MQ server, you might get the following error:

"MQ: Could not Connect the Queue Manager '<queue-manager-name>': The Server was expecting an SSL connection."

  • The MQ server needs to provide a certificate that's issued by a trusted certificate authority.

  • The MQ server requires that you define the cipher specification to use with TLS connections. However, for security purposes and to include the best security suites, the Windows operating system sends a set of supported cipher specifications.

    The operating system where the MQ server runs chooses the suites to use. To make the configuration match, you have to change your MQ server setup so that the cipher specification matches the option chosen in the TLS negotiation.

    When you try to connect, the MQ server logs an event message that the connection attempt failed because the MQ server chose the incorrect cipher specification. The event message contains the cipher specification that the MQ server chose from the list. In the server-connection channel configuration, update the cipher specification to match the cipher specification in the event message.

Next steps