Free MuleSoft CONNECT Keynote & Expo Pass Available!

Register now+
Nav

Microsoft Service Bus Connector

Select

The Microsoft Service Bus connector enables message integration with Windows Service Bus on-premises and Azure Service Bus on the cloud. The connector supports communication with queues, topics, and event hubs through AMQP 1.0. In addition, dynamic discovery and provisioning of Service Bus objects is possible using the built-in management API.

Prerequisites

This document assumes that you are familiar with Service Bus, Mule, Anypoint Connectors, Anypoint Studio, Mule concepts, elements in a Mule flow, and Global Elements.

You need credentials to test your connection to your target resource. It can be one of the following credentials type:

  • SAS (Shared Access Signature)

  • Username and Password

  • Windows credentials type

For hardware and software requirements and compatibility information, see the Connector Release Notes.

To use this connector with Maven, view the pom.xml dependency information in the Dependency Snippets in Anypoint Exchange.

The connector supports the following Service Bus versions:

  • Microsoft Azure Service Bus (Cloud)

  • Microsoft Windows Service Bus (on-premises)

What’s New in this Connector

Support for Mule 4 has been added.

To Connect in Design Center

  1. Click a trigger such as an HTTP Listener or Scheduler trigger.

  2. If needed, you can create a global element by selecting Reusable Configuration.

  3. To configure an HTTP Listener for the connector, set these fields:

    • Protocol: Protocol selected for the HTTP endpoint, it can be HTTP or HTTPS (secure).

    • Host: IP address where your Mule application listens for requests.

    • Port: Port address where your Mule application listens for requests.

    • Base Path: path where your Mule application listens for requests.

  4. Click the plus sign to add a component.

  5. Select the connector as a component.

  6. Configure one of Global elements for the connector.

    • SAS (Shared Access Signature):

      General:

      Field Description

      Connection Type

      Shared Access Signature

      Blob Storage Connection:

      Field Description

      Storage Access Key

      Access key from your Storage.

      Container Name

      Container’s name.

      Storage Account Name

      Account name from storage.

      Connection:

      Field Description

      Service Namespace

      The namespace for the Azure Service Bus Service within your subscription.

      Shared Access Signature

      The unique security token when you have a single security profile to access all your service resources. In this case when the token expires, the connector cannot reconnect automatically and you need to stop running the flow to update this configuration setting with a new token.

    • Username and Password:

      General:

      Field Description

      Connection Type

      Username Password

      Blob Storage Connection:

      Field Description

      Storage Access Key

      Access key from your Storage

      Container Name

      Container’s name

      Storage Account Name

      Account name from storage

      Connection:

      Field Description

      Shared Access Key Name

      Enter the name of access key configured on the namespace. Any access key created at a lower level (such as, a Topic level Shared Key) does not work with this option, unless you disable the connectivity test at startup.

      Shared Access Key

      Enter the 256-bit primary key.

      Service Namespace

      Enter the name of the service namespace to address Service Bus resources within your application.

    • Windows:

      General:

      Field Description

      Connection Type

      Windows

      Connection:

      Field Description

      Service Namespace

      Enter the name of the service namespace to address Service Bus resources within your application.

      Username

      Enter the user to use for authentication.

      Password

      Enter the password of the user.

      Fully Qualified Domain Name

      Enter the fully qualified domain name of your Windows Service Bus server

      Port

      Enter the server port number.

      Disable SSL Certificate Validation

      If you are using a self-signed SSL certificate, select this check box.

      Skip connectivity test

      In case you have limited access to Windows Service Bus resources and you want to skip the connectivity test performed at startup you need to set this setting to true.

To Connect in Anypoint Studio 7

You can use this connector in Anypoint Studio by adding it as a dependency in your Mule application.

To Install Connector in Studio

  1. In Anypoint Studio, click the Exchange icon in the Studio task bar.

  2. Click Login in Anypoint Exchange.

  3. Search for the connector and click Install.

  4. Follow the prompts to install the connector.

You can ensure a Maven dependency was added for this connector:

  1. Open your Mule project in Anypoint Studio.

  2. Ensure that the connector as a dependency is in the pom.xml file:

    <dependency>
      <groupId>com.mulesoft.connectors</groupId>
      <artifactId>mule-microsoft-service-bus-connector</artifactId>
      <version>2.0.0</version>
      <classifier>mule-plugin</classifier>
    </dependency>

To Configure in Studio

  1. Drag and drop the connector to the Studio Canvas.

  2. Configure the Global element for the connector

    Configuration values for each Connection type are the same as in To Connect in Design Center section.

Use Case: Get Queue list

Use Case Studio Flow

  1. Create a new Mule Application in Studio and select an HTTP Listener as a Source in the new flow.

  2. Add a new HTTP Listener Configuration global element.

  3. Fill in the Host and port parameters with the following values:

    Parameter Value

    Host

    0.0.0.0

    Port

    8081

  4. Click Save.

  5. Assign your new Global configuration to your HTTP Listener.

  6. Fill in HTTP Listener path with /servicebus value.

  7. Drag and drop a new Service Bus component into the flow.

  8. Configure the Service Bus connector global element with its environment values.

  9. Add a transform message before the Connector and add an output like this:

    
                
             
    1
    2
    3
    4
    
    %dw 2.0
    output application/json
    ---
    payload
  10. Save and run the project as a Mule Application.

  11. To test the app, navigate to http://127.0.0.1:8081/servicebus

Use Case: XML

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
xmlns:servicebus="http://www.mulesoft.org/schema/mule/servicebus"
        xmlns:http="http://www.mulesoft.org/schema/mule/http"
        xmlns="http://www.mulesoft.org/schema/mule/core"
        xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
        http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/servicebus
http://www.mulesoft.org/schema/mule/servicebus/current/mule-servicebus.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
        <configuration-properties file="mule-app.properties" />
        <http:listener-config name="HTTP_Listener_config"
          doc:name="HTTP Listener config">
                <http:listener-connection host="0.0.0.0" port="8081" />
        </http:listener-config>
        <servicebus:config name="Servicebus_Config"
          doc:name="Servicebus Config">
                <servicebus:windows-connection namespace="${config.namespace}"
                 username="${config.username}" password="${config.password}"
                 fqdn="${config.fqdn}" />
        </servicebus:config>
        <flow name="servicebusFlow">
                <http:listener doc:name="Listener"
                config-ref="HTTP_Listener_config"
                path="/servicebus"/>
                <servicebus:queues-list doc:name="Queues list"
                config-ref="Servicebus_Config"/>
                <ee:transform doc:name="Object to JSON">
                        <ee:message >
                                <ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
payload]]></ee:set-payload>
                        </ee:message>
                </ee:transform>
        </flow>
</mule>

About Service Bus Authentication

To send and receive messages through the Service Bus connector, authentication is performed through AMQP.

For the REST Management API, the authentication scheme differs based on the Microsoft Service Bus version. The Windows Service Bus running on premises uses OAuth and the Azure Service Bus running in the cloud uses a Shared Access Key token.

The Windows Service Bus uses a self-signed SSL certificate to secure the communication via AMQP and HTTPS. The connector won’t run if this certificate is not locally imported in the box running Mule, unless the Ignore SSL warning check is enabled.

To Enable SSL Checks By Importing The Certificate

  1. Use the PowerShell cmdlet Get-SBAutoGeneratedCA to download the certificate locally to the computer running the Windows Service Bus. For the purposes of this tutorial, assume the certificate file is exported to %temp%\AutoGeneratedCA.cer. A download link for the cmdlet is provided in the See Also section of this guide.

  2. Go to %programfiles%\Java\jre8. Verify that the bin\keytool.exe tool exists, and that lib\security\cacerts exists. Note that you must be running as Administrator to perform a certificate import with Keytool.exe. Otherwise, an Access Denied error occurs.

  3. Enter the following command: bin\keytool.exe –list –keystore lib\security\cacerts

  4. Import the auto-generated Service Bus certificate by running the following command: bin\keytool.exe –importcert –alias AppServerGeneratedSBCA –file %temp%\AutoGeneratedCA.cer –keystore lib\security\cacerts –v

  5. You are prompted for the password (the default is “changeit”). If you do not know the password, you cannot perform the import. When the tool asks you whether to trust the certificate, enter Y (Yes).

About SAS Based Authentication

In addition to the connection schemes that require a username and password, the connector provides a connection in which authentication is SAS based (only for Azure) which allows you to set the authentication token for the Service Bus Service without requiring the username and password for it.

As the SAS token schema is URI based (that is, you can assign different authorization access to your resources based on their URIs) the connection supports multiple ways of providing the authentication tokens needed. The most trivial and simple case is when you have a single profile that authorizes access to all your resources by using an specific root URI which is the base endpoint that your service exposes. If you need to provide different access tokens on different resources, use a setting that allows you to configure them according to the resources the connector needs while running.

Extending the mechanisms described above to provide the authentication token, you can implement a custom token provider to allow the connector requests for security tokens as needed. You need to resolve each request and return a fresh token every time the connector asks for one. As the token has an expiration time within it, this mechanism allows the connector to re-authenticate with the target resource when the token expires. This is not allowed with the previous mechanisms described above where the tokens are fixed at configuration time before the flow runs.

The following are the available settings for the Shared Access Signature connection:

  • Service Namespace: The namespace for the Azure Service Bus Service within your subscription.

  • Shared Access Signature: (Optional) The unique security token when you set up just one security profile to access all your service resources. In this case when the token has expired, the connector cannot reconnect automatically and you need to stop running the flow to update this configuration setting with a new token.

Within the advanced section you can find:

  • SAS Tokens List: (Optional) The list of security tokens the connector needs to access for the different URIs when the security profiles for each are different. When any of the tokens expires, the connector cannot reconnect to the URI linked to that token and you need to stop running the flow to update this configuration setting with a new set of tokens.

  • SAS Tokens Provider: (Optional) A Spring bean reference implementing the org.mule.modules.microsoftservicebus.connection.providers.SharedAccessSignatureProvider interface. If you set an instance of a token provider here, it is your responsibility to provide a fresh token for each URI the connector requires access to (according to your security profiles). In this case each time a token expires, the connector requests a new one, which is provided by your implementation, and reconnection to the target URI is done seamlessly.

  • Max Connections: (Optional) Maximum number of connections to keep in pool to be reused by producer. If set to "-1" it creates a new connection each time.

At least one of the optional settings shown above must be provided.

In all cases, the token format you should provide is a string that must comply with the following pattern:

SharedAccessSignature sr=[resource_uri]&sig=[signature]&se=[ttl]&skn=[profile]

The sr parameter value can start with an https or amqps protocol depending on the operation you perform on the target resource.

For example:

SharedAccessSignature sr=amqps%3a%2f%2fmynamespace.servicebus.windows.net%2fMyQueue&sig=pSrfJn5uRTiepgOTjBpjcf2gw%2bG34S1MYdCfkQkTC8A%3d&se=101&skn=OperationalPolicyKey`

About Performance Considerations

The Claims Based Security mechanism required to authenticate to Azure Service Bus uses a SAS token that exchanges messages with a special node. The latest impacts on connector’s performance as tokens are exchanged per request to achieve connection security setup using targeted tokens related to the resource being accessed. This has been optimized, starting from version 1.2, to impact performance as least as possible. If your scenario requires sending several messages with high throughput, use a connection strategy that requires setting the username and password. This is the simpler way to authenticate to Azure Service Bus with the connector while achieving better throughput, although it requires you to write the password for the shared access key name you are using.

As said before, if you are experiencing performance issues when using the SAS strategy, update to version 1.2 or higher. The optimized mechanism has lower performance impact on receiving and sending operations as the AMQP container and cache (respectively) keep the connection alive and token exchange messages occur only when setting up the connection and/or in case of token expiration.

About Restricted Access Policies

If you have restricted access to your resources and have a security policy with permissions only at resource level, the connector cannot perform its connectivity test when it starts. The test targets the root level of your namespace which might be forbidden due to the customized policy applied to the shared access key. For these scenarios, skip the connectivity test with the configuration option available for this purpose, otherwise the connector cannot start up.