Create a service principle to access Dynamics 365 Web API
Dustin Miner
- posted on
- Comments Off on Create a service principle to access Dynamics 365 Web API
This post is currently being updated
Consider a C# 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 an access token issued. This token can then be placed in the request when calling the API.
This post takes this example to 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
- Configure an Azure Function to connect and authenticate to 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
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
When it’s required for C# code to interact with Dynamics 365 online, it’s necessary for Azure Active Directory to generate an access token in order to interact with Dynamics 365. 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
3.) The Microsoft.Xrm.Tooling.Connector.CrmServiceClient() can be used to authenticate to Dynamics 365 and then call the Service Organization (it uses ADAL)
Appendix
CrmServiceClient
C# code which uses CrmServiceClient to authenticate to Dynamics 365 via the Azure AD (Figures 12 & 13). Referring to Figure 12, the object crmSvc could then be used to execute a Create, Update, RetrieveMultple…
Note: Microsoft is now recommends using the Dataverse ServiceClient rather than CrmServceClient.
Note: ideally the client secret displayed in Figure 13 should be stored in the Azure key vault
Further reading
Using Postman with the Power Platform
XRM.Navigation.navigateto a html web resource
References
OAuth Application Users in Dynamics 365
