This post is currently being updated
Consider a console app, an Azure function or even a tool such as Postman which needs to call the Dynamics 365 Web API. Dynamics 365 is secured by Azure Active Directory using OAuth 2.0. So, in order to call the API, the caller needs to be authenticated by the AAD and issued with an access token. This token can then be placed in the request when calling the API.
This post describes how to:
- Register an app in Azure AD to implement OAuth2 authentication to the Dynamics 365 API
- Create an non-interactive application user in Dynamics 365 to authorise access to the DEV environment
- Discuss options for how a console app, Azure function could be authenticated in order to interact with the Dynamics API
Note:
- A user (user principle) sends a user/password (e.g. in a popup dialog) to authenticate in Azure AD
- A system (service principle) sends a Application Id/Client secret to authenticate in Azure AD, without any human involvement
- The post describes registering an app for Dynamics 365. A similar could be followed to register an app for other API such as SharePoint
Register an app (service principal) in Azure AD
Within the Azure portal (https://portal.azure.com), click on ‘App registrations’ & then ‘New registration’ (Figure 1)
Enter the application name and then click on ‘Register’ (Figure 2). In this example, one app registration is created to connect to three Dynamics 365 environments DEV, SIT & UAT. Note that one app could have been created for each Dynamics 365 environment
Click on ‘View API permissions’ (Figure 3). Take note of the Application Id (client Id) which will be required in the section below ‘Create a application user in the Dynamics 365 DEV environment’
Then click on ‘Add a permission’ (Figure 4)
Select ‘Dynamics 365’ (Figure 5) to request API permissions
For delegated permissions, select the user_impersonation checkbox (Figure 6)
To create a client secret for the app, select ‘New client secret’ (Figure 7). Take note of the client secret as this won’t be displayed again
The app setup is now complete (Figure 8)
This app can then be used to connect to the various Dynamics 365 / Dataverse environments
https://contosodev.crm6.dynamics.com
https://contososit.crm6.dynamics.com
https://contosouat.crm6.dynamics.com
Create a application user in the Dynamics 365 DEV environment
This next step is to create an application user in the https://contosodev.crm6.dyanmics.com environment (these steps would need to be repeated for SIT and UAT). This is required to control the level of access to the Dynamics 365 / Dataverse Web API. For example, to specify if the application user can delete records in Dataverse.
Note: This section describes the legacy way to create an Application User. The new way is via the Power Platform Admin Center isn’t described in this post.
Select the ‘Application Users’ view (Figure 9)
Enter the Application Id which was generated earlier (Figure 3). Note that the user …GatewayAppUser@…onmicrosoft.com has already been created within AAD
Choose the required security role (not System Administrator as this would be a security risk)
Now it’s possible to connect to the API as explained in the following section
Authenticating to Dynamics 365 via Azure Active Directory
Now that a service principle has been created, it’s now possible to write some code (e.g. a console app, an Azure function) to interact with Dynamics 365 online. The newly created client id/secret will be sent Azure Active Directory (implementing OAuth), with the AAD generating an access token. The following are three options for being able to achieve this
1.) The Microsoft Authentication Library (MSAL) NuGet package can be used to authenticate to the Dynamics 365 Web API
2.) The httpClient.PostAsync can be used to authenticate the Dynamics 365 Web API
https://github.com/anilvem1/CrmWebApiOAuth
For these two options, the access token (which is just a long string e.g. eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6…) can then be placed in the header of the Web API request
If the code being written (to interact with Dynamics 365 online) is a .NET language such as C#, the following option can be used
3.) The Dataverse .NET client class ServiceClient. This uses MSAL for authenication and after being authenticated, can execute Service Organisation calls such as Create, Update, RetrieveMultiple as well as functions such as WhoAmI
Getting started with the Dataverse ServiceClient
There is also the legacy class Microsoft.Xrm.Tooling.Connector.CrmServiceClient(). See appendix below
Appendix
CrmServiceClient
Note that CrmServiceClient supports several authentication types. Figure 12 demonstrates OAuth with Azure AD (using ADAL for authentication). Figure 13 (in the first green box) demonstrates using a network credential and then a connection string
The CrmServiceClient wraps both OrganizationServiceProxy and OrganizationWebProxyClient. The second green box (Figure 13) illustrates the casting of the OrganizationWebProxyClient object to the IOrganizationService Interface. The third green box illustrates connecting to Dyamics CRM using OrganizationServiceProxy is now depreciated.
Further reading
Dynamics 365 / Dataverse authentication considerations
Using Postman with the Power Platform
XRM.Navigation.navigateto a html web resource
References
OAuth Application Users in Dynamics 365