Walkthrough: Register a Dynamics 365 Customer Engagement app with Active Directory

Article
01/06/2023

This walkthrough describes how to register a desktop client or mobile application so that it can connect to and authenticate with the Dynamics 365 Server and access the Web services. Once registered, an application can access the Web services using HTTP requests with the Web API or by the SDK API for .NET.

Prerequisites

For an 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 Dynamics 365 Customer Engagement (on-premises) deployment services role and the AD FS server.
The on-premises server must be configured to use claims authentication.
The redirect URL for your application. Instructions for finding that URL are provided in the section named Obtain the redirect URL.

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.

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 Dynamics 365 Customer Engagement (on-premises) (IFD)

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

The ISV or Partner performs the following tasks:

Configures the Customer Engagement on-premises (IFD) server and AD FS server using Windows PowerShell commands that are provided later in this section.
Provides the client ID and server address URL information to the customer.

The customer or other person performs the following tasks:

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

Dynamics 365 Server setup

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

Configure claims settings

Log on as administrator on the Customer Engagement server that hosts the deployment service role and open a Windows PowerShell command window.
Add the Customer EngagementWindows PowerShell snap-in (Microsoft.Crm.PowerShell.dll). More information: Administer the deployment using Windows PowerShell
```
Add-PSSnapin Microsoft.Crm.PowerShell  
```

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

Log on to the AD FS server as administrator and open a Windows PowerShell command window.
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 Visual Studio by opening the Tools menu and clicking Create GUID.