Walkthrough: Register a CRM app with Active Directory

 

Applies To: Dynamics CRM 2013

This walkthrough describes how to register an external rich desktop client or mobile application so that it can connect to and authenticate with the Microsoft Dynamics CRM server and access the web services. Once registered, an application can access the web services using HTTP requests through the server’s SOAP or OData endpoints. This walkthrough applies to both Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online.

Prerequisites

For a Microsoft Dynamics CRM 2013 on-premises or Internet-facing deployment (IFD):

• Windows Server 2012 R2 with AD FS.

• You must have administrator access to the server hosting the Microsoft Dynamics CRM 2013 deployment services role and the AD FS server.

• The on-premises server must be configured to use claims authentication.

For a Microsoft Dynamics CRM Online deployment:

• The user must have a Microsoft Dynamics CRM Online system user account with administrator role for the Microsoft Office 365 subscription.

For either deployment type, you must know the redirect URI for your application. Instructions for finding that URI are provided in the section at the end of this topic named Obtain the redirect URI.

In This Topic

App registration for CRM on-premises (IFD)

App registration for CRM Online

Obtain the redirect URI

App registration for CRM on-premises (IFD)

Scenario: A customer or other person registers a custom application to access organization data on a CRM server provided by an ISV or Partner.

The ISV or Partner performs the following tasks:

1. Configures the CRM on-premises (IFD) server and AD FS server using Windows PowerShell commands that are provided later in this section.

2. Provides the client ID and server address URL information to the customer.

The customer or other person performs the following tasks:

1. Configures the external application by entering the client ID and server address URL in the app as instructed.

CRM server setup

To configure the CRM server to enable federated claims, follow these steps.

Configure claims settings

1. Log on as administrator on the CRM server that hosts the deployment service role and open a Windows PowerShell command window.

2. Add the CRM Windows PowerShell snap-in (Microsoft.Crm.PowerShell.dll). More information: Use PowerShell to Call the Deployment Web Service

   Add-PSSnapin Microsoft.Crm.PowerShell
   

3. Enter the following Windows PowerShell commands.

   $fedurl = Get-CrmSetting -SettingType ClaimsSettings
   $fedurl.FederationProviderType = 1
   $fedurl.Enabled = 1;
   Set-CrmSetting $fedurl
   

AD FS server setup

To register the external application with AD FS, follow these steps.

Register the application in Active Directory

1. Log on to the AD FS server as administrator and open a Windows PowerShell command window.

2. Enter the following command.

   Add-AdfsClient -ClientId <CLIENT_ID> -Name <APP_NAME> -RedirectUri <REDIRECT_URI>
   

   Where <CLIENT_ID> is a unique number, <APP_NAME> is a name for the application, and <REDIRECT_URI> is any valid URI that AD FS is to redirect to after authentication has completed. It is recommended that the client ID be a GUID. You can generate a GUID in Microsoft Visual Studio by opening the Tools menu and clicking Create GUID.

App registration for CRM Online

Scenario: A person with a CRM Online system user account accesses organization data through a rich desktop client or mobile app.

The end user performs the following tasks:

1. Registers the external application in Microsoft Azure and provides a redirect URI during the registration process. The URI can be any valid and appropriate URI. The Microsoft Azure app registration process results in the generation of a client ID string.

2. Configures the application by entering the client ID and redirect URI in the app’s authentication code or configuration file when instructed on the Microsoft Azure app registration page.

Scenario: An ISV creates and registers an app that later published in the app store. The ISV’s customers download the app from the store and use it to connect to their Microsoft Dynamics CRM Online organization.

The ISV performs the following tasks:

1. Registers the app in the ISV’s tenant using the steps provided in the previous scenario (above).

Each customer that downloads the app performs the following tasks:

1. When accessing a CRM organization in the customer’s tenant, the customer will be presented with a consent form.

2. The customer reads the information on the form and clicks OK to consent.

3. (Optional) The customer register’s the app in the customer’s tenant.

For native apps, the customer has to consent each time he or she is prompted to authenticate again. For web apps, the customer is only asked to consent one time. The workaround to bypass the consent form is for the customer to register the app in the customer’s tenant. Follow the instructions below in the procedure named “Register an application with Microsoft Azure”.

Register an application with Microsoft Azure

1. Sign in to the Microsoft Azure management portal by using a Microsoft Office 365 account with administrator permission. Use an account in the same subscription (tenant) as you intend to register the app with.

   You must sign up for a Microsoft Azure account by using a credit card if you do not have an account. However, the account is free and your credit card will not be charged if you only follow the procedures called out in this topic to register one or more apps. More information: Active Directory Pricing Details

2. Click or tap Active Directory in the left column of the page. You may need to scroll the left column to see the Active Directory icon and label.

3. Click or tap the desired tenant directory in the directory list.

   

   If your CRM tenant directory is not shown in the directory list, click or tap Add, and then select Use existing directory in the dialog box. Follow the prompts and instructions provided, and then go back to step 1.

4. With the target directory selected, click or tap Applications, and then click or tap Add.

5. In the dialog box, click or tap Add an application my organization is developing.

6. When prompted, enter a name for your application, click or tap a type: Web Application or Native Client Application, and then click or tap the right arrow to continue.

7. Continue providing the requested information and complete the app registration process.

8. With the tab of the newly registered app selected, click or tap Update Your Code. Insert the provided redirect URI and client ID in the authentication code of your app.

   

9. With the tab of the newly registered app selected, click or tap Configure.

10. Set the app permissions as shown in the figure below.

    

Register an application with AD FS

• If you’re federating users between an IFD server and Microsoft Dynamics CRM Online, and you want to use the app with either server, you must register the application with both Microsoft Dynamics CRM Online and Active Directory Federation Services (AD FS) on the IFD server. Follow the steps provided in this topic. Your IFD server must be running Windows Server 2012 R2.

Obtain the redirect URI

One method to obtain the redirect URI is to execute the following line of code in a debug session. In a WinJS debug session, select the RawUri property.

string redirectUri = WebAuthenticationBroker.GetCurrentApplicationCallbackUri().ToString();

Dim redirectUri As String = WebAuthenticationBroker.GetCurrentApplicationCallbackUri().ToString()

Windows.Security.Authentication.Web.WebAuthenticationBroker.getCurrentApplicationCallbackUri()

You can then use the string value returned from the method call when you register the app. The C# line of code is shown in the topic Sample: Windows 8 desktop modern OData app.

See Also

Authenticate the user with the web services
Authenticate users with Microsoft Dynamics CRM 2013 web services