Walkthrough: Register an Azure-aware plug-in with the CRM plug-in registration tool
Applies To: CRM 2016 on-prem, CRM Online
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 2016 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 2016 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 Create a new service namespace.
If you are using Microsoft Dynamics CRM 2016, 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.
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.
Run the Plug-in Registration tool.
Click Create New Connection.
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.
If you check Always display list of available orgs, you are presented with a list of organizations that you belong to after you click Login. This enables you to choose the organization that you want to register the service endpoint with. Otherwise, your default organization is used.
Enter the indicated information about the server and login account, and then click Login.
Create a service endpoint configuration
Follow the steps below to register a Microsoft Azure service endpoint.
Select the tab of the organization that you want to register a service endpoint with.
In the toolbar of the tab, click Register and then Register New Service Endpoint.
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
A name for your service endpoint registration.
A description of this endpoint registration.
Solution Namespace (field)
The name of the solution’s service namespace.
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.
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.
Save & Verify Authentication (button)
Saves the configuration you entered and verifies that ACS is configured correctly.
Saves the configuration you entered and closes the dialog.
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, click Save & Configure ACS, and then follow the instructions in the next section of this walkthrough. If you have already configured ACS, click Save & Verify Authentication or Save and continue with the instructions in Register a service endpoint step for an event.
Follow the steps below to configure Microsoft Azure Active Directory Access Control Service (ACS).
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
The management key for your solution. You can obtain this key value from the Azure Management Portal.
In the left pane, click Service Bus, and then select the target namespace in the list.
At the bottom of the page, click 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”.
The public certificate file that was used to configure Microsoft Dynamics CRM for integration with Microsoft Azure.
For Microsoft Dynamics CRM Online 2016 Update and Microsoft Dynamics CRM 2016 (on-premises), you can download this certificate file from the server. In the Microsoft Dynamics CRM web application click Settings > Customizations, and then click Developer Resources. Download and save the certificate file using the link provided below Microsoft Azure Service Bus Issuer Certificate.
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.
Click Configure ACS. A log of the configuration process is displayed in the output area of the form.
Click 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.
Select the service endpoint that you previously registered in the tree view of the tool.
Navigate to the Register menu and click Register New Step.
Fill out the Register New Step dialog box for an account create event as shown in the following figure.
Click 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.
Open the Microsoft Dynamics CRM web application for the same organization that you registered the service endpoint under.
Click the Create button , and then click Account.
Enter an account name, for example Adventure Works Cycle, into the Account Name field, and then click Save.
Wait about 10 minutes for the Microsoft Azure Service Bus post to occur.
Click Settings > System Jobs.
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 click Unregister.
Microsoft Dynamics CRM 2016 and Microsoft Dynamics CRM Online
Send comments about this topic to Microsoft.
© 2015 Microsoft. All rights reserved.