Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Windows Gateway Services Guide

Windows Gateway Services provides functionality used by the MuleSoft Microsoft Dynamics CRM and MSMQ connectors.

WindowsGateway

The Windows Gateway leverages the following technologies and frameworks:

  • ASP.NET Web API exposes an HTTP web API that sends and receives raw messages.

  • OWIN provides the HTTP layer. Open Web Interface for .NET (OWIN) is an open specification for decoupling applications from web server functionality, which provides a layer for making all the HTTP concerns independent of the hosting platform.

  • Katana provides the OWIN Microsoft implementation, which handles self and IIS hosting for OWIN applications.

For information on MSMQ, see the MSMQ Connector User Guide.

Prerequisite

Java Cryptography Extensions needs to be installed on the server where Windows Gateway Service is installed. The JCE package is required to allow the Connector to use HTTPS to communicate securely. Please install JCE for your Java version from the Sun website:

Installing the Windows Gateway Services

  1. Download the Windows Gateway Services installer from here. Unzip the software distribution. For more information, see the Windows Gateway Services Guide.

  2. Double-click the AnyPoint-Windows-Gateway-Service.exe file.  

  3. Click Options to change the installation location, or click Install to start the installation. 

  4. Copy the Authentication Token that displays for use when you configure the PowerShell connector in Anypoint Studio. For more information, see the Windows PowerShell Connector Guide. After you copy the token, click Install.

  5. After the installation completes, the installer gives you the option to view the readme.txt file with additional instructions. 

  6. Click Finish to exit.

  7. The installation creates the new Anypoint Gateway Windows service, which the installer starts.

    AnypointGateway

To view the running service in Windows 7, when the Control Panel View by option is set to Small icons, click Control Panel > Administrative Tools > Services. The service appears as:

ServicesTool

Configuring the Anypoint Gateway for Windows Service

The install location for the Windows Service is c:\Program Files(x86)\Anypoint Gateway for Windows. This folder contains the Mule.SelfHost.exe executable, the Mule.SelfHost.exe.config configuration file and PowerShell scripts to automate configuration tasks.

Note: If the configuration file doesn’t appear in the folder, in Windows 7, when the Control Panel View by option is set to Small icons, click Control Panel > Folder Options > View > Show hidden files, folders, and drives.

The executable starts a new web server at port 9333, which only accepts secure connections using HTTPS. You can change the port number and the authentication token for the gateway in the Mule.SelfHost.exe.config configuration file:


        
     
1
2
3
4
5
6
<appSettings>
    <!-- Configure the service to listen on the following address. -->
    <add key="OwinHostAddress" value="https://+:9333/"/>
    <!-- Token that must be sent by the Mule connector's client in the Authorization header when accessing the Rest API. -->
    <add key="mule-auth-token" value="3nGdw7W+G1fSO2YBEHDmpo4N1Tg="/>
</appSettings>

This web server uses a self-signed SSL certificate auto-generated during installation. The certificate is in the Personal folder of the Local Computer certificate store:

MMC_Personal_Certs

Because the Windows service relies on http.sys for self-hosting the web server, any change in the port number or SSL certificate requires reconfiguring Windows. The Register-SslCert.ps1 PowerShell script in the installation directory handles this task. If the port or certificate changes, run the following command from a http://en.wikipedia.org/wiki/Windows_PowerShell[PowerShell] console:

Register-SslCert.ps1 <certificate-thumbprint> <windows-account> <port>

  • <certificate-thumbprint>: The thumbprint of the SSL certificate. It must be stored in the Personal Folder of the Local Store Account.

  • <windows-account>: Windows User or Group that receives permissions to register the port. The account impersonating the Windows service or console application must be part of this group.

  • <port>: HTTP port – Must be 9333.

Example:

Register-SslCert.ps1 a495cbf8c4af496f1ef81efb224c8097d039f922 everyone 9333

Security Considerations

For all connectors leveraging the Windows Gateway Services, the service first authenticates the direct caller, which is the connector running in the Mule ESB.

Service Authentication

The authentication of the connector is done through a security token included in the HTTP Authorization header. This token is included on every HTTP request to the Gateway using the Mule scheme. The following example shows how MSMQ leverages the Gateway to connect to a specific queue:


          
       
1
2
3
4
GET: https://localhost:9333/msmq?count=50
Authorization: mule test-token
Mule-Msmq-Queue-Name: .\private$\out
Mule-Api-Version: 1.0

Configure the token on the connector and also in the Gateway configuration file. The following configuration sections show how the token is configured in both sides.

Connector Configuration


           
        
1
2
3
<msmq:config name="MSMQ" doc:name="MSMQ" accessToken="test-token" rootQueueName=".\private$\qout" serviceAddress="localhost:9333">
  <msmq:connection-pooling-profile initialisationPolicy="INITIALISE_ONE" exhaustedAction="WHEN_EXHAUSTED_GROW"/>
</msmq:config>

Gateway Configuration


           
        
1
2
3
<appSettings>   
    <add key="mule-auth-token" value="test-token"/>
</appSettings>

Note: The installer for the Windows Gateway service automatically generates a cryptographically secure token for use by callers upon first install. This token is displayed and placed upon the clipboard during installation for easy copying into a Mule application.

User Authentication

Users executing the call on behalf of a Gateway-served connector authenticate through two custom HTTP headers, mule-impersonate-username and mule-impersonate-password

When using user authentication, the queue in any connector type is marked to require authentication. These two headers represent the Windows credentials of an existing user in the Active Directory forest where the Windows Gateway service is running, or a local account on the machine hosting the service. When these HTTP headers are included in an HTTP Request, the Windows Gateway service authenticates and impersonates this user before queuing or dequeuing a message from a connector. This provides the ability to configure the correct access control list permissions on the queue using Windows credentials.

Windows Gateway Service Troubleshooting

The Windows Gateway service leverages the built-in .NET tracing system. The basic premise is simple, tracing messages are sent through switches to listeners, which are tied to a specific storage medium. The listeners for the trace source used by the connector are available in the configuration file:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<sharedListeners>
   <add name="console" type="System.Diagnostics.ConsoleTraceListener" />
   <add name="file" type="System.Diagnostics.TextWriterTraceListener" initializeData="Mule.Gateway.log" />
   <add name="etw" type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="{47EA5BF3-802B-4351-9EED-7A96485323AC}" />
</sharedListeners>
 
<sources>
    <source name="Mule.Gateway">
        <listeners>
            <clear />
            <add name="console" />
            <add name="etw"/>
        </listeners>
    </source>
</sources> 

The previous example configures three listeners for the output console, for files, and for Event Tracing for Windows (ETW). The trace source for the connector Mule.Gateway is configured to output the traces to the console and ETW only.

Changing the Tracing Level

The Windows Gateway is configured by default to log everything, which is the Verbose level. Other possible levels are:

  • Error: Output error handling messages

  • Warning: Output warnings and error handling messages

  • Info: Output informational messages, warnings and error handling messages

  • Off: Disable tracing

You can configure the levels at switch level in the configuration file:


          
       
1
2
3
<switches>
    <add name="Mule.Msmq" value="Verbose" />
</switches>

Event Tracing for Windows (ETW)

ETW is a very efficient built-in publish and subscribe mechanism for doing event tracing at the kernel level. There is little overhead in using this feature compared to other traditional tracing solutions that rely on I/O for storing the traces in persistence storage such as files or databases. As a built-in mechanism in Windows, many of the operating systems services and components use this feature as well. For that reason, not only can you troubleshoot the application but also many of the OS components involved in the same execution.

In ETW, there are applications publishing events in queues (or providers) and other applications consuming events from those queues in real-time through ETW sessions. When an event is published in a provider, it goes nowhere unless there is a session collecting events on that queue. (The events are not persisted).

The tracing system in .NET includes a trace listener for ETW, EventProviderTraceListener, which you can configure with a session identifier, which ETW uses to collect traces:


          
       
1
2
3
<sharedListeners>
   <add name="etw"type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="{47EA5BF3-802B-4351-9EED-7A96485323AC}"/>
</sharedListeners>

In the example, the session is associated with this identifier: 
{47EA5BF3-802B-4351-9EED-7A96485323AC}

Collect Session Traces

To collect session traces:

  1. Open a Windows console and run this command to start a new session:

    
                  
               
    1
    
    logman start mysession -p {47EA5BF3-802B-4351-9EED-7A96485323AC} -o etwtrace.etl -ets
  2. Run this command to stop the session:

    
                  
               
    1
    
    logman stop mysession -ets

    This generates the etwtrace.etl file with the tracing session data.

  3. Run this command to generate a human readable file:


           
        
1
tracerpt etwtrace.etl

This command transfers useful information into the dumpfile.xml text file. For more information, see http://technet.microsoft.com/en-us/library/cc732700.aspx[Tracerpt].