Walkthrough: Register an Azure-aware plug-in with the CRM plug-in registration tool

Applies To: Dynamics CRM 2015

This walkthrough demonstrates how to configure Microsoft Azure Active Directory Access Control Service (ACS) and register a service endpoint step using the Plug-in Registration tool. Once configured, Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online can post the execution context of the current operation to a Microsoft Azure solution endpoint. For this walkthrough, the step is registered to post the execution context of the CreateRequest message for an Account entity to the Microsoft Azure Service Bus.

The following prerequisites must be completed before you start this walkthrough:

• Access to the Plug-in Registration tool. You can find the tool’s executable file in the Tools\PluginRegistration folder of the SDK. Download the Microsoft Dynamics CRM SDK package. 

• Obtain an account on Microsoft Dynamics CRM 2015 or Microsoft Dynamics CRM Online.

• Your system user account must have the System Customizer or System Administrator role. For more information, see How role-based security can be used to control access to entities in Microsoft Dynamics CRM.

• Have access to a Microsoft Azure platform service namespace that uses ACS version 2, to which Microsoft Dynamics CRM will post a message. For more information about creating an ACS namespace see d689ec2b-1752-44bf-9e5f-135a2d828af3#Create_namespace.

• If you are using Microsoft Dynamics CRM 2015, the server must be configured for Microsoft Azure integration according to the instructions in the topic Configure Azure integration with Microsoft Dynamics CRM.

• There must be a listener application actively listening to the specified solution endpoint for Microsoft Dynamics CRM to successfully post to the Microsoft Azure Service Bus. For more information, see Write a listener for a Microsoft Azure solution.

Steps

This walkthrough contains the following steps:

1. Connect to the Microsoft Dynamics CRM server

2. Create a service endpoint configuration

3. Configure ACS

4. Register a service endpoint step for an event

5. Test the endpoint registration

Connect to the Microsoft Dynamics CRM server

Follow the steps below to connect to the Microsoft Dynamics CRM server using the Plug-in Registration tool.

1. Run the Plug-in Registration tool.

2. Choose Create New Connection.

3. In the Login dialog box, select the deployment type radio button corresponding to the Microsoft Dynamics CRM server you intend to register a service endpoint with. The On-premises radio button includes an IFD deployment, the Online button is for the Windows Live provider of Microsoft Dynamics CRM Online, and the Office 365 button is for the Microsoft Online Services provider of Microsoft Dynamics CRM Online.

   Login form for an online deployment

   Login form for an on-premises deployment

4. If you check Always display list of available orgs, you are presented with a list of organizations that you belong to after you choose Login. This enables you to choose the organization that you want to register the service endpoint with. Otherwise, your default organization is used.

5. Enter the indicated information about the server and login account, and then choose Login.

Create a service endpoint configuration

Follow the steps below to register a Microsoft Azure service endpoint.

1. Select the tab of the organization that you want to register a service endpoint with.

2. In the toolbar of the tab, choose Register and then Register New Service Endpoint.

3. Fill out the Service Endpoint Registration dialog box with the information related to your solution as shown in the following figure and described in the table that follows. Make sure the contract you specify is the same contract used by your solution’s listener application.

   

   UI Element	description
   Name (field)	A name for your service endpoint registration.
   Description (field)	A description of this endpoint registration.
   Solution Namespace (field)	The name of the solution’s service namespace.
   Path (field)	The path of your project. For example, given a service endpoint URL of https://crmsdkdemo-sb.accesscontrol.windows.net/TwoWayService/Demo, the path is TwoWayService/Demo.
   Contract (drop-down menu)	The endpoint contract. A listener application must use this contract to read the posted message. For more information, see Write a listener for a Microsoft Azure solution.
   Claim (drop-down menu)	The claims to send to Microsoft Azure. Use None for the standard claim. Specify UserId or UserInfo to send additional information about the logged on user.
   Federated Mode (checkbox)	Check this box to use federated mode.
   ID (field)	Non-writeable field that is filled in automatically with the ID of your endpoint configuration.
   Save & Configure ACS (button)	Saves the configuration you entered and automates the process of configuring ACS for you. Provides an interactive way to accomplish what is described in the topic Walkthrough: Configure Microsoft Azure ACS for integration with Microsoft Dynamics CRM 2015.
   Save & Verify Authentication (button)	Saves the configuration you entered and verifies that ACS is configured correctly.
   Save (button)	Saves the configuration you entered and closes the dialog.

4. If you have not yet configured ACS integration with Microsoft Dynamics CRM, and you would like the Plug-in Registration tool to do the configuration for you, choose Save & Configure ACS, and then follow the instructions in the next section of this walkthrough. If you have already configured ACS, choose Save & Verify Authentication or Save and continue with the instructions in Register a service endpoint step for an event.

Configure ACS

Follow the steps below to configure Microsoft Azure Active Directory Access Control Service (ACS).

1. After choosing Save & Configure ACS, the ACS Configuration dialog box appears. Enter the appropriate data values into the form fields as described in the following table.

   Field Name	Description
   Management Key	The management key for your solution. You can obtain this key value from the Azure Management Portal. Obtain a Management Key for a Service Bus Namespace Sign in to the Azure portal. In the left pane, choose Service Bus, and then select the target namespace in the list. At the bottom of the page, choose Connection Information. In the Access connection information dialog box, the Default Key is shown. This is the management key. Note If you have changed the symmetric key, enter that key instead of the default key into the Management Key field. If you fail to do so, you may receive errors with a description like this: “ACS50012: Authentication failed”.
   Certificate File	The public certificate file that was used to configure Microsoft Dynamics CRM for integration with Microsoft Azure. For Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online 2015 Update, you can download this certificate file from the server. In the Microsoft Dynamics CRM web application choose Settings > Customizations, and then choose Developer Resources. Download and save the certificate file using the link provided below Microsoft Azure Service Bus Issuer Certificate.
   Issuer Name	The name of the issuer. This name must be the same name that was used to configure Microsoft Dynamics CRM for Microsoft Azure integration. You can obtain the issuer name from the Developer Resources webpage mentioned in the previous description. For more information, see Configure Azure integration with Microsoft Dynamics CRM.

2. Choose Configure ACS. A log of the configuration process is displayed in the output area of the form.

3. Choose Close.

4. Choose Save & Verify Authentication in the Service Endpoint Registration dialog box. After the verification is finished you can close the dialog boxes.

Register a service endpoint step for an event

Follow the steps below to register a step for an event on the service endpoint.

1. Select the service endpoint that you previously registered in the tree view of the tool.

2. Navigate to the Register menu and choose Register New Step.

3. Fill out the Register New Step dialog box for an account create event as shown in the following figure.

   

4. Choose Register New Step.

Microsoft Dynamics CRM will now post the current message containing the execution context to the service bus whenever an account is created. The post is performed asynchronously and is not executed immediately.

Test the endpoint registration

After you register the endpoint you can test it. A listener must be running or a queue available on the target endpoint for the service bus post from the plug-in to happen.

1. Open the Microsoft Dynamics CRM web application for the same organization that you registered the service endpoint under.

2. Choose the Create button , and then choose Account.

3. Enter an account name, for example Adventure Works Cycle, into the Account Name field, and then choose Save.

4. Wait about 10 minutes for the Microsoft Azure Service Bus post to occur.

5. Choose Settings > System Jobs.

6. Open the system job that has the same name that you specified for your service endpoint. Check the status to see if the post was successful, is waiting, or failed.

You can now unregister the endpoint, if so desired, by selecting it in the tool’s tree view and choose Unregister.

See Also

Azure extensions for Microsoft Dynamics CRM
Azure integration with Microsoft Dynamics CRM
Active Directory and claims-based authentication

© 2016 Microsoft. All rights reserved. Copyright