Microsoft Dynamics AX Services and Windows Azure Service Bus

Introduction

 

In Microsoft Dynamics AX 2012 R2 developers can deploy services using the Application Integration Framework (AIF) over HTTP. This works great for applications that needed to communicate with Microsoft Dynamics AX over an enterprise network. However added complexities arise when applications need to communicate with Microsoft Dynamics AX over the Internet or through external networks, complexities that require re-configuring firewalls and building additional infrastructure components.

 

With the AIF Windows Azure Service Bus Adapter, AIF can now be configured to work seamlessly with the Windows Azure Service Bus. The Service Bus acts as a message relay, allowing Microsoft Dynamics AX-bound service messages sent over the Internet to reach Microsoft Dynamics AX service endpoints on a private network, and allowing the message responses to be returned to the client application.

 

The process for publishing Microsoft Dynamics AX services to work with the AIF Windows Azure Service Bus Adapter is much the same as the process to publish Microsoft Dynamics AX services using the HTTP adapter in Microsoft Dynamics AX 2012 R2. This article provides a high-level overview of the required infrastructure as well as the steps needed to publish a service using the AIF Windows Azure Service Bus Adapter.

 

Before you are able to publish such a service yourself, you will need to complete the one-time setup instructions that detail creating a Windows Azure account, Service Bus namespace, Access Control Services (ACS) namespace, and Microsoft ADFS configuration as covered in the article Microsoft Dynamics AX 2012 White Paper: Developing Mobile Apps.

You will also need to install the AIF Windows Azure Service Bus Adapter Hotfix for Microsoft Dynamics AX 2012 R2 or install Cumulative Update 6 (CU6) for Microsoft Dynamics 2012 R2 from PartnerSource.

 

Overview

 

Below is an architecture overview detailing the flow of information between a Client Application on an external network (the Internet) communicating with X++ services running on Microsoft Dynamics AX in a firewalled enterprise network. The major components and their behaviors are:

1.  The Cloud/Client Application
   • Prompts user for credentials. Creates an authentication request using Windows Claims-Based Authentication for the Active Directory Federation Services (ADFS).
   • Uses tokens from the Microsoft ADFS and the Windows Azure ACS to make X++ service calls through the Service Bus
2. The ADFS
   • Acts as a Security Token Service (STS) for the application.
   • The ADFS establishes a trust with the ACS as part of configuration.
3. The Windows Azure Service Bus and Access Control Services
   • The Service Bus receives service calls over HTTP from the Cloud/Client Applications.
   • Each Service Bus namespace has a coupled ACS, which is configured to authenticate service calls. The ACS requires configuration steps that are dependent on the ADFS settings.
4. Microsoft Dynamics AX and IIS 7.5
   • The AIF is used to publish services just as was done in Microsoft Dynamics AX 2012 R2. Services for the Cloud/Client Applications must be published using the Service Bus adapter.
   • AX will deploy a WCF routing service into IIS 7.5 when the service is published. The routing service requires no configuration after the service is configured using the AIF.

Architecture Visual Representation

 

Click for larger image

The authentication process is as follows:

1. The client app sends user credentials to ADFS. The client calls the ADFS Security Token System (STS) with the user credentials and requests a Security Assertion Markup Language (SAML) token. The SAML token is signed but unencrypted. This is because the token is used by Microsoft Dynamics AX 2012 R2 to identify the user.

2. ADFS computer sends token A to the client.

3. The client app sends token A (the SAML token) to ACS.

4. ACS first verifies that the SAML token corresponds to a user with permissions to call the Service Bus, and then sends token B to the client app. Token B is a Single Web Token (SWT) that has the claim required to make the service call to the Service Bus.

5. The client app makes a call to the Service Bus and passes tokens A and B along with the service request. The Service Bus consumes the SWT (token B), but allows the SAML token (token A) stored in a custom header to pass through. The SAML token is intended for use by an authentication component hosted in IIS.

6. The Service Bus relays the SAML token and service message through to the Windows Communication Foundation (WCF) Routing service. Because the WCF Routing service has established an outbound connection to the Service Bus, messages from the Service Bus are allowed through the firewall.

7. The AOS receives the SAML token and the service message from the WCF Routing service.

   • • An authentication component for the service is invoked by IIS as part of the authentication process. (he authentication component is detailed in Microsoft Dynamics AX 2012 White Paper: Developing Mobile Apps.

       The authentication component performs the following steps while processing the message:

   a. Reads the custom header from the message.

   b. Extracts the SAML token from the custom header.

   c. Validates the token by verifying that the signature of the token matches the signature expected
   by the ADFS STS.

   d. Extracts the claims from the token.

   e. Creates the claims identity and principal and sets them on the security context of the message.

   1. • An AIF extension gets the user identity from the message security context and sets it on the message being forwarded to the AOS. The AOS authenticates the caller specified in the headers set on the message by the AIF extension.

8. The AOS processes the service call, and sends the Response message to the WCF routing service hosted in IIS.

9. The WCF routing service sends the service response back through the Service Bus.

10. The Service Bus sends the service response back to the client app. 

Getting started with the AIF Windows Azure Service Bus Adapter

In order to get started using the AIF Windows Azure Service Bus Adapter you must first fulfill the following prerequisites as detailed in Microsoft Dynamics AX 2012 White Paper: Developing Mobile Apps.

• Configure your Service Bus and ACS namespaces
• Configure a Microsoft ADFS
  OR
  Contact the administrator of your local Microsoft ADFS and request that your ACS be added as a relying party application
• Verify the AX component Web Services on IIS 7.5 is installed
• Install the AIF Windows Azure Service Bus Adapter hotfix: https://support.microsoft.com/kb/2845539
• Create a service authentication component 

 

After fulfilling the prerequisites above you will be able to complete the following steps to make an AX service available through the Service Bus:

1. Create an X++ service from an existing X++ class
2. Expose an existing X++ method as an operation on the service
3. Register your Service Bus namespace with the AIF
4. Publish your X++ service to the Service Bus using the AIF Windows Azure Service Bus Adapter

 These steps are summarized below, and detailed in full in Microsoft Dynamics AX 2012 White Paper: Developing Mobile Apps.

Create an X++ service from an existing X++ class

1. Open the Microsoft Dynamics AX MorphX Development Workspace
2. Open the X++ Class containing the X++ methods you wish to expose as services
   1. Supply a SysEntryPointAttribute to each method
   2. Save your changes

Expose an existing X++ method as an operation on the service

1. Open the Microsoft Dynamics AX MorphX Development Workspace 
2. Create a new service by right-clicking the Services node in the AOT and selecting New Service
   1. Supply a name for the service
   2. Set the Class property to the name of an X++ class containing methods with the SysEnrtyPointAttribute
3. Right-click the new service and add a new operation
   1. Select all methods you wish to expose as operations on this service
4. Right-click the new service, click Add-Ins and then click Register Service

 

For more information on registering services and service operations, see:
https://technet.microsoft.com/en-us/library/gg731906.aspx

Register your Service Bus namespace with AIF

1. Open the Microsoft Dynamics AX Client
2. Click System administration > Setup > Services and Application Integration Framework > Windows Azure Service Bus Configuration
3. Complete the Windows Azure Service Bus Configuration form (this is complete only once for each Service Bus namespace)
   1. Windows Azure service namespace: Supply the name your Service Bus namespace
   2. Windows Azure service key issuer name: Supply the Access Key issuer name of your Service Bus
   3. Windows Azure service key issuer secret: Supply the Access Key of your Service Bus
   4. Deployment web site: Select the IIS website that will host the routing service
   5. Class name: Select the authentication component registered while completing the prerequisites
   6. Click Configure
      1. Trusted Issuer Name: Supply the name of the X.509 certificate issuer as obtained while completing the prerequisites
      2. Trusted Issuer Thumbprint: Supply the X.509 certificate thumbprint obtained while completing the prerequisites
   7. RSA Key Container Name: Supply the name of the key container created while completing the prerequisites
   8. Description: Supply a description of the Service Bus namespace being configured

Publish your service to the Service Bus using the AIF Windows Azure Service Bus Adapter

1. Click System Administration > Services and Application Integration Framework > Inbound Ports
2. Click New to create a new port
   1. Port Name: Type the name of the port
   2. Description: Provide a description of the services this port hosts
   3. Adapter: Select Windows Azure Service Bus
   4. Click the dropdown button beside the URI filed to open the Select Windows Azure Service Bus Namespace form
      1. Select the namespace you registered
      2. Click OK
         
   5. Click the Service Operations button below Service Contract customizations
      1. Locate the X++ service you wish to expose
      2. Select all of the Operations on your service you wish to publish by highlighting each one and clicking the "<" button
      3. Click Close
3. In the Inbound Ports window, highlight the port you created in the left-hand pane
4. Click the Activate button at the top

Your X++ service is now published to IIS 7.5 and listening to messages from the Service Bus. 

 

Downloads

The article Microsoft Dynamics AX 2012 White Paper: Developing Mobile Apps details all steps necessary to create an authentication component and encrypt sensitive configuration information. The steps in that document require the downloads available below. 

• Sample authentication classes

• Encryption scripts