Walkthrough: Register a Dynamics 365 app with Azure Active Directory

  • Article

 

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

This walkthrough describes how to register an application with Microsoft Azure Active Directory so that it can connect to the Microsoft Dynamics 365 server, authenticate using OAuth, and access the web services. Once registered, an application can access the web services using HTTP requests with the Web API or the web client proxy classes of the Organization Service. This walkthrough applies to both Microsoft Dynamics 365 (online & on-premises) when using OAuth authentication in your application.

Prerequisites

For an on-premises or Internet-facing deployment (IFD):

  • The server must be configured to use claims authentication and have OAuth authentication enabled.

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

For a Microsoft Dynamics 365 (online) deployment:

  • The user must have a Microsoft Dynamics 365 (online) system user account with administrator role for the Microsoft Office 365 subscription.

  • A Microsoft Azure subscription 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 OAuth authentication

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 OAuth authentication

Scenario: A person with a Dynamics 365 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 365 (online) or Internet-facing deployment (IFD) 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 Dynamics 365 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 365 (online) is not available in your Azure subscription, 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. Click 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 the desired tenant directory in the directory list.

    List of available Active Directory entries

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

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

  6. When prompted, enter a name for your application, pick a type: Web Application or Native Client Application, and then click 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, click 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, click Configure or Configure access to web APIs in other applications.

  10. Click Add application and then set the app permissions as shown in the following figure. Select the + icon on the Dynamics 365 (online) line item and then select the check mark to exit the dialog.

    Set permissions to the CRM Online application

  11. In the Dynamics 365 (online)Delegated Permissions drop down list, check Access Dynamics 365 (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 365 (online), and you want to use the app with either server, you must register the application with both Microsoft Dynamics 365 (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 in Microsoft Dynamics 365

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright