Walkthrough: Configure Microsoft Azure ACS for integration with Microsoft Dynamics CRM 2013

  • Article

 

Applies To: Dynamics CRM 2013

This walkthrough guides you through configuring the Microsoft Azure Access Control Service (ACS) 2.0 issuer, scope, and rules to allow a listener application to read the Microsoft Dynamics CRM messages posted to the Microsoft Azure Service Bus. This walkthrough applies to integration with any deployment type of Microsoft Dynamics CRM.

Tip

The Plug-in Registration tool provided in the SDK is the recommended way to automate the configuration of ACS for basic scenarios. Refer to the section named “Configure ACS” in the topic Walkthrough: Register an Azure-aware plug-in with the CRM plug-in registration tool for instructions on how to configure ACS using the tool. For more advanced scenarios, you’ll need to use the ACS Management Portal described later in this topic. Download the Microsoft Dynamics CRM SDK package.

As a prerequisite to this walkthrough, if you’re running Microsoft Dynamics CRM 2013 (on-premises or IFD), configure Microsoft Dynamics CRM 2013 for Microsoft Azure integration. For more information, see Walkthrough: Configure CRM for integration with Microsoft Azure. Microsoft Dynamics CRM Online is pre-configured for Microsoft Azure integration.

In This Topic

Create a new service namespace

Create a service identity (issuer)

Create a rule group and a rule

Configure the scope

Create a new service namespace

If you have an existing ACS version 2 service namespace that you want to use, continue with the next section named Create a service identity (issuer).

Warning

Do not use the Microsoft Azure portal to create a service namespace for use with Dynamics CRM. The portal will create a SAS namespace but CRM requires an ACS namespace.

Use PowerShell commands to create a new service namespace

  1. Download and install the Microsoft Azure PowerShell module. More information:  How to install and configure Azure PowerShell

  2. From the Start menu, search for and run the Microsoft Azure PowerShell program and enter the following commands after the > prompt.

    > Add-AzureAccount
> New-AzureSBNamespace –Name YOUR_NAMESPACE -Location "YOUR_LOCATION" -CreateACSNamespace $true

    Note

    Version 0.8.9 or later of Azure PowerShell supports the –CreateACSNamespace parameter in the New-AzureSBNamespace command. If your installed version of Azure PowerShell doesn’t support the –CreateACSNamespace parameter, install the latest version. To see the version of Azure PowerShell that you’re using, enter the command Get-Module Azure.

    After you enter Add-AzureAccount, you’ll be prompted to provide the credentials of your Azure subscription account. Substitute an appropriate namespace name for YOUR_NAMESPACE and an approximate location for YOUR_LOCATION. The supported locations are: Central US, East US, East US 2, North Central US, South Central US, West US, North Europe, West Europe, East Asia, Southeast Asia, Brazil South, Japan East, and Japan West.

After you enter these commands, the namespace is created and you should see output that looks similar to the following text.

Name                  : mynamespace
Region                : Central US
DefaultKey            : 1eKDTIYEACFP7Geiy5QV/hqJnWHeroJyKk/PBzv42Rw=
Status                : Active
CreatedAt             : 8/25/2014 3:36:47 PM
AcsManagementEndpoint : https://mynamespace-sb.accesscontrol.windows.net/
ServiceBusEndpoint    : https://mynamespace.servicebus.windows.net/
ConnectionString      : Endpoint=sb://mynamespace.servicebus.windows.net/;SharedSecretIssuer=owner;SharedSecretValue=1
                        eKDTIYEACFP7Geiy5QV/hqJnWHeroJyKk/PBzv42Rw=

Create a service identity (issuer)

  1. If you haven’t already done so, navigate to the Microsoft Azure site and then sign in to the portal using your Microsoft Azure account.

  2. In the management portal, click Service Bus and then select your existing namespace in the list.

  3. Click Connection Information.

  4. At the bottom of the form, click Open ACS Management Portal.

  5. Under Service Settings, select Service identities, and then click Add. The next step defines an issuer name.

  6. On the Add Service Identity page, enter a name for the issuer identity. This must be the same issuer name that Microsoft Dynamics CRM is configured with. You can find this issuer name in the CRM web application by first selecting Settings, then selecting Customizations, and then clicking Developer Resources.

  7. Select a credential type of X.509 Certificate.

  8. Browse to the location of the certificate on your local box. Obtain the certificate by clicking the Download Certificate link on the Developer Resources page of the CRM web application.

  9. Click Save, and if another Save button is shown, click Save again.

If you’re working with Microsoft Dynamics CRM Online and see an indication that the certificate you obtained from that server is expired, you can ignore that warning.

Create a rule group and a rule

Create a rule for the target scope that will allow Microsoft Dynamics CRM to send or “post” to the Microsoft Azure Service Bus. You do this by configuring ACS to map the input “Organization” claim from Microsoft Dynamics CRM to the output “Send” claim of the Microsoft Azure Service Bus.

First, create a rule group by following these steps.

  1. Below Trust relationships, select Rule groups.

  2. Click Add.

  3. Enter a name for the rule group and select Save.

Next, add a claim rule to the rule group.

  1. On the Edit Rule Group page, click Add.

  2. In the If section of the page, select Access Control Service.

  3. For the input claim type, select Enter type and then enter https://schemas.microsoft.com/xrm/2011/Claims/Organization.

  4. For the input claim value, select Enter value, and then enter the name of a Microsoft Dynamics CRM organization.

    For an Internet-facing or on-premises deployment, enter the unique name of the desired organization in lowercase characters. You can find this name on the Developer Resources page of the CRM web application next to the Organization Unique Name label. To navigate to that page in the Web application, select Settings, select Customizations, and then click Developer Resources.

    For a Microsoft Dynamics CRM Online deployment, specify the complete hostname part of the Web service URL. For example, given a URL of https://myorg.crm.dynamics.com/main.aspx, the host name part is myorg.crm.dynamics.com.

  5. In the Then section, for the output claim type, click Select type and then select the http://docs.oasis-open.org/wsfed/authorization/200706/claims/action item from the drop-down list.

  6. For the output claim value, select Enter value, and enter a value of Send for the output claim.

  7. Add a description of the rule (optional). For example, you could type: “Allow the Contoso organization to send to the Microsoft Azure Service Bus.”

  8. Click Save.

Configure the scope

The following steps describe how to configure the Microsoft Azure Service Bus scope of ACS for a normal mode post by Microsoft Dynamics CRM. Defining a scope provides more restricted access to the service namespace.

  1. Below Trust relationships, select Relying party applications, and then click Add.

  2. On the Add Relying Party Application page, enter a display name for the relying party. For example, enter internal. This name is the scope name.

  3. Enter the realm URI of your Microsoft Azure service endpoint and append the scope name, for example, https://crmsdkdemo.servicebus.windows.net/internal.

  4. Enter the return URL, which can be the same value as the realm URI you just entered.

  5. Select a token format of SAML 2.0.

  6. You may optionally increase the token lifetime value.

  7. Make sure the Windows Live ID identity provider is selected.

  8. Select the name of the rule group you created previously. If the check box next to your rule appears ghosted, first clear the check box that is currently checked, and then select the check box for your rule.

  9. Click Save.

Important

If you’re using federated mode, the process is similar to what is described in this walkthrough. You would add an issuer, and create a scope specific to the Uri (recommended) or a new base scope. You will need to configure both –sb and non–sb scopes. You may also need to create a token policy for the creating the issuer.

See Also

Azure extensions for Microsoft Dynamics CRM 2013
Walkthrough: Configure CRM for integration with Microsoft Azure
Configure Microsoft Azure integration with Microsoft Dynamics CRM 2013
ACS Management Portal