Walkthrough: Register a CRM app with Active Directory

  • Article

 

Applies To: Dynamics CRM 2015

This walkthrough describes how to register a 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 2015 and Microsoft Dynamics CRM Online 2015 Update.

Prerequisites

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

  • A Windows Server 2012 R2 with AD FS.

  • You must have administrator access to the server hosting the Microsoft Dynamics CRM 2015 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.

  • A Microsoft Azure account for application registration. A trial account will also work.

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

In This Topic

Obtain the redirect URI

App registration for CRM on-premises (IFD)

App registration for CRM Online

Obtain the redirect URI

One method to obtain the redirect URI for a native client Windows application is to execute the following line of code in a debug session of your application and examine the returned URI value. 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()

The WebAuthenticationBroker class can be found in the Windows.Security.Authentication.Web namespace. 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.

For a non-Windows native client application such as a console application, use any valid URI value. In this case, the URI doesn’t need to actually exist but it must be unique in the tenant.

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: TechNet: Administer the deployment using Windows PowerShell

    Add-PSSnapin Microsoft.Crm.PowerShell

  3. Enter the following Windows PowerShell commands.

    $ClaimsSettings = Get-CrmSetting -SettingType OAuthClaimsSettings
$ClaimsSettings.Enabled = $true
Set-CrmSetting -Setting $ClaimsSettings

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 desktop client or mobile application.

The end user or application developer 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 is 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.

Register an application with Microsoft Azure

  1. Sign in to the Microsoft Azure management portal by using an account with administrator permission. You must use an account in the same Office 365 subscription (tenant) as you intend to register the app with. You can also access the Microsoft Azure portal through the Office 365 admin center by expanding the ADMIN item in the left navigation pane and selecting Azure AD.

    If you don’t have an Azure tenant (account) or you do have one but your Office 365 subscription with Microsoft Dynamics CRM Online is not available in your Azure account, following the instructions in the topic Set up Azure Active Directory access for your Developer Site to associate the two accounts.

    If you don’t have an account, you can sign up for one by using a credit card. However, the account is free for application registration and your credit card won’t 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. Choose 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. Choose the desired tenant directory in the directory list.

    List of available Active Directory entries

    If your CRM tenant directory isn’t shown in the directory list, choose 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, choose Applications (near the top of the page), and then choose Add.

  5. In the What do you want to do? dialog box, choose Add an application my organization is developing.

  6. When prompted, enter a name for your application, choose a type: Web Application or Native Client Application, and then choose the right arrow to continue. Click a question mark ? for more information on the appropriate values for each input field.

  7. Continue providing the requested information and complete the app registration process by choosing the check mark icon.

  8. With the tab of the newly registered app selected, choose Update Your Code. Copy the provided redirect URI and client ID. You’ll need to insert these values into your application’s authentication code or app.config file where appropriate. For some example code, see the topic Sample: Windows 8 desktop modern OData app.

    Generated client ID in Dynamics CRM

  9. With the tab of the newly registered app selected, choose Configure or Configure access to web APIs in other applications.

  10. Choose Add application and then set the app permissions as shown in the following figure. Select the + icon on the Dynamics CRM Online line item and then select the check mark to exit the dialog.

    Set permissions to the CRM Online application

  11. In the Dynamics CRM Online  Delegated Permissions drop down list, check Access CRM Online as organization users.

    Add application permission in Dynamics CRM

    For more information about registering an app with Azure Active Directory see Adding an Application.

  12. Select SAVE.

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.

See Also

Adding, Updating, and Removing an Application
Authenticate the user with the web services
Authenticate users with Microsoft Dynamics CRM web services

© 2016 Microsoft. All rights reserved. Copyright