Walkthrough: Register a Dynamics 365 app with Active Directory

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

This walkthrough describes how to register a desktop client or mobile application so that it can connect to and authenticate with the Microsoft Dynamics 365 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 Microsoft Dynamics 365.

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 Microsoft Dynamics 365 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 URI.

In This Topic

Obtain the redirect URI

App registration for Dynamics 365 on-premises (IFD)

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

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

The ISV or Partner performs the following tasks:

  1. Configures the Dynamics 365 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.

Dynamics 365 server setup

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

Configure claims settings

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

  2. Add the Dynamics 365Windows 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.

See Also

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

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright