Dynamics 365-integrate without requiring a licensed user
Introduction
The goal of this blog post is to inform you about the benefits of application users, an approach of authenticating and interacting with Dynamics 365 online for your application/s without requiring a licensed user account. This approach is particularly useful for larger projects where you exceed the 5 non-interactive user accounts.
**Updated October 2019 for new API limitations introduced
̶T̶h̶i̶s̶ ̶a̶p̶p̶r̶o̶a̶c̶h̶ ̶b̶e̶c̶o̶m̶e̶s̶ ̶m̶o̶r̶e̶ ̶b̶e̶n̶e̶f̶i̶c̶i̶a̶l̶ ̶a̶s̶ ̶M̶i̶c̶r̶o̶s̶o̶f̶t̶ ̶h̶a̶s̶ ̶r̶e̶c̶e̶n̶t̶l̶y̶ ̶a̶n̶n̶o̶u̶n̶c̶e̶d̶ ̶a̶ ̶n̶e̶w̶ ̶A̶P̶I̶ ̶t̶h̶r̶e̶s̶h̶o̶l̶d̶ ̶ ̶i̶n̶ ̶t̶h̶e̶ ̶a̶r̶t̶i̶c̶l̶e̶ ̶i̶t̶ ̶s̶t̶a̶t̶e̶s̶:̶
̶“̶W̶e̶ ̶l̶i̶m̶i̶t̶ ̶t̶h̶e̶ ̶n̶u̶m̶b̶e̶r̶ ̶o̶f̶ ̶A̶P̶I̶ ̶r̶e̶q̶u̶e̶s̶t̶s̶ ̶m̶a̶d̶e̶ ̶b̶y̶ ̶e̶a̶c̶h̶ ̶u̶s̶e̶r̶,̶ ̶p̶e̶r̶ ̶o̶r̶g̶a̶n̶i̶z̶a̶t̶i̶o̶n̶ ̶i̶n̶s̶t̶a̶n̶c̶e̶,̶ ̶w̶i̶t̶h̶i̶n̶ ̶a̶ ̶f̶i̶v̶e̶ ̶m̶i̶n̶u̶t̶e̶ ̶s̶l̶i̶d̶i̶n̶g̶ ̶w̶i̶n̶d̶o̶w̶.̶ ̶“̶
̶A̶c̶c̶o̶r̶d̶i̶n̶g̶ ̶t̶o̶ ̶t̶h̶e̶ ̶e̶r̶r̶o̶r̶ ̶m̶e̶s̶s̶a̶g̶e̶ ̶t̶h̶e̶ ̶n̶e̶w̶ ̶l̶i̶m̶i̶t̶ ̶i̶s̶ ̶“̶N̶u̶m̶b̶e̶r̶ ̶o̶f̶ ̶r̶e̶q̶u̶e̶s̶t̶s̶ ̶e̶x̶c̶e̶e̶d̶e̶d̶ ̶t̶h̶e̶ ̶l̶i̶m̶i̶t̶ ̶o̶f̶ ̶4̶0̶0̶0̶,̶ ̶m̶e̶a̶s̶u̶r̶e̶d̶ ̶o̶v̶e̶r̶ ̶t̶i̶m̶e̶ ̶w̶i̶n̶d̶o̶w̶ ̶o̶f̶ ̶3̶0̶0̶ ̶s̶e̶c̶o̶n̶d̶s̶.̶”̶
̶T̶h̶e̶ ̶a̶p̶p̶l̶i̶c̶a̶t̶i̶o̶n̶ ̶u̶s̶e̶r̶ ̶m̶i̶g̶h̶t̶ ̶a̶l̶l̶o̶w̶ ̶y̶o̶u̶ ̶t̶o̶ ̶b̶e̶t̶t̶e̶r̶ ̶s̶e̶g̶m̶e̶n̶t̶ ̶y̶o̶u̶r̶ ̶a̶p̶p̶l̶i̶c̶a̶t̶i̶o̶n̶\̶s̶ ̶a̶n̶d̶ ̶h̶a̶n̶d̶l̶e̶ ̶l̶o̶a̶d̶(̶f̶u̶r̶t̶h̶e̶r̶ ̶t̶e̶s̶t̶i̶n̶g̶ ̶r̶e̶q̶u̶i̶r̶e̶d̶)̶ ̶w̶i̶t̶h̶o̶u̶t̶ ̶r̶e̶a̶c̶h̶i̶n̶g̶ ̶t̶h̶i̶s̶ ̶l̶i̶m̶i̶t̶a̶t̶i̶o̶n̶.̶N̶o̶t̶e̶ ̶t̶h̶i̶s̶ ̶s̶h̶o̶u̶l̶d̶ ̶n̶o̶t̶ ̶b̶e̶ ̶u̶s̶e̶d̶ ̶b̶y̶ ̶n̶o̶r̶m̶a̶l̶ ̶u̶s̶e̶r̶s̶ ̶a̶s̶ ̶t̶h̶e̶s̶e̶ ̶a̶c̶c̶o̶u̶n̶t̶s̶ ̶a̶r̶e̶ ̶n̶o̶t̶ ̶s̶u̶p̶p̶o̶s̶e̶d̶ ̶t̶o̶ ̶a̶c̶c̶e̶s̶s̶ ̶t̶h̶e̶ ̶U̶I̶.̶
Per the article here on the additional API limits:
Effective October 2019, to help ensure service levels, availability, and quality, there are entitlement limits to the number of requests users can make each day across model-driven apps in Dynamics 365 (such as Dynamics 365 Sales and Dynamics 365 Customer Service) PowerApps, and Microsoft Flow.
for example:
User licenses
Number of API requests / 24 hours
Dynamics 365 Enterprise applications:20,000
Dynamics 365 Professional :10,000
Common Data Service also provides the ability to have identities that do not require any user license to interact with the service. There are three types of these users:
These non-licensed users have a base pool larger than the comparative licensed user for example “If a tenant has at least one Dynamics 365 enterprise subscription, they will get 100,000 requests per 24 hours”
So what happens if this is exceeded and what can be done about it?
Per the FAQ
Will my Integrations stop working if application users exceeds Base Request capacity?
Integrations will not be stopped for occasional and reasonable overages at this point of time. Administrators would be notified about overages and will be able to add PowerApps and Microsoft Flow request capacity to be compliant.
and per the document here
PowerApps and Microsoft Flow capacity add-on
PowerApps and Microsoft Flow capacity add-on allows customers to purchase additional requests which can be assigned to any user who has a PowerApps/Microsoft Flow license as well as Dynamics 365 license. These can be assigned to an application, and administrative and non-interactive users.
Each capacity add-on provides an additional 10,000 requests/24 hours which can be assigned to any user. Multiple capacity add-ons can also be assigned to the same user.
Non-interactive user account
First thing to look at is something called a non-interactive user account:
According to Microsoft
“It is used for programmatic access to and from Dynamics 365 for Customer Engagement apps between applications. A non-interactive user account lets these applications or tools, such as a Dynamics 365 for Customer Engagement apps to ERP connector, authenticate and access Dynamics 365 for Customer Engagement apps (online), without requiring a Dynamics 365 for Customer Engagement apps (online) license. For each instance of Dynamics 365 for Customer Engagement apps (online), you can create up to five non-interactive user accounts.”
More information on this can be found here: https://docs.microsoft.com/en-us/dynamics365/customer-engagement/admin/create-users-assign-online-security-roles#create-a-non-interactive-user-account
The downside to (non-interactive user accounts) is you are limited to 5 per instance.
Application user
The 5 limitation of service user accounts can be too limiting, you can use application user licences, Microsoft describe as:
“Introduced in December 2016 Update for Dynamics 365 (online), you can use server-to-server (S2S) authentication to securely and seamlessly communicate with December 2016 update for Dynamics 365 (online) with your web applications and services. S2S authentication is the common way that apps registered on Microsoft AppSource use to access the Dynamics 365 (online), version 8.2 data of their subscribers. All operations performed by your application or service using S2S will be performed as the application user you provide rather than as the user who is accessing your application.
All application users are created with a non-interactive user account, however they are not counted towards the five non-interactive user accounts limit. In addition, there is no limit on how many application users you can create in an instance.”
More info on this can be found here: https://docs.microsoft.com/en-us/dynamics365/customer-engagement/admin/create-users-assign-online-security-roles#create-an-application-user
So great there is a way of authenticating and accessing Dynamics 365 data that:
· Does not require a license
· You can create as many of these application accounts as you like
· If you want an app to share a user account as they have the same permission requirements you can give them each their own security key which can have its own expiry date or can be revoked as required
· For each application you can give least possible permissions to do what is required (IE the app can have its own user account and security role which only has access permissions required to do its job)
How do we set this up?
1. Follow these steps by Microsoft to Register a Dynamics 365 for Customer Engagement app with Azure Active Director https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/walkthrough-register-dynamics-365-app-azure-active-directory and take note of the “Application ID” of the application you just created
2. Follow the instructions here for creating a security key for the app you registered the step before and note down the generated “security key” https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#get-application-id-and-authentication-key
3. On your Dynamics 365 instance you want this to access go to Settings > Security > Users
4. On the view selector, select “Application Users”
5. Select “New”
6. On the create new user form, if not already selected change the form used to “User:application user”
7. Create the new user
a. User Name: give it a username
b. Application ID: this will be the application id of the Azure app you registered and took note of earlier
c. Full Name: give it a full name
d. Primary Email: give it an email address
8. After the user is created, like normal user accounts it will need to be given a security role, this can be either one of the out of box security roles or my recommendation is to create a security role that just has the permissions required for the app to function as required.
Code example using an application account
I will show you the method of authentication using the Dynamics 365 web API and a C# console app: Note, this uses “Microsoft.IdentityModel.Clients.ActiveDirectory” which I added via NuGet
using System;using System.Threading.Tasks;using System.Net.Http;using System.Net.Http.Headers;using Microsoft.IdentityModel.Clients.ActiveDirectory;namespace ConnectToDynamics365CE{class Program{static void Main(string[] args){//enter in the url for your Dynamics 365 online instance below, for the way i’ve coded it make sure it ends with “.com/” also you will probably want to store this as a variable (not in the code) rather than hard coding these in for deployment automation purposesstring D365URL = “https://yourinstance.crm11.dynamics.com/";//this will be the query you will be submiting to the API, for the instance defined by the URL above for example purposes I am just querying top 3 contactsstring query = “contacts?$top=3”;//create a string for your applicationID and Secret key you will probably want to store this as a variable (not in the code) rather than hard coding these in for security and deployment automation purposesstring applicationId = “applicationID”;string secret = “Secretkey”;// create a string which calls the Dynamics 365 api using the above variables and stores the response: you don’t need to store it as as a string you could deserialise the response json to an object ectstring D365response = QueryDynamics365API(D365URL, query, applicationId, secret).Result;// this is just writing out the response body either to prove it works or give you an indication of why it failedConsole.WriteLine(D365response);}public static async Task<string> QueryDynamics365API(string D365URL, string query, string applicationId, string secret){// this is taking the Dynamics 365 URL and adding the API url bitsstring api = D365URL + “api/data/v9.1/”;//This thing I found is quite cool, you send a request to get the authorisation URL from the Dynamcs 365 instance API you want to connect to, although it does have an issue which I will explain in next commentAuthenticationParameters ap = await AuthenticationParameters.CreateFromResourceUrlAsync(new Uri(api));//The ADAL (Azure Active Directory Authentication Libraries) this uses (V4) is much stricter in regards to authentication url you can use, the request to get the auth url done just before returns the url with “/oauth2/authorize”appended which if you send a request for a access token using v4 with this appended it will return an error, hence the below line of code removing “/oauth2/authorize” from the urlap.Authority = ap.Authority.Replace(“/oauth2/authorize”, “”);//creates Client credentials using the applicationId and SecretClientCredential creds = new ClientCredential(applicationId, secret);// Authenticate the registered application with Azure Active Directory.AuthenticationContext authContext = new AuthenticationContext(ap.Authority);AuthenticationResult authResult = await authContext.AcquireTokenAsync(ap.Resource, creds);//stores the token from the authResultstring token = authResult.AccessToken;// instantiating the request status and giving default value, this will change if request succeeds. only used for demo purposesstring requestStatus = “error: “;// creates a new http client to send api requestusing (HttpClient httpClient = new HttpClient()){//adds authorisation using the token generated earlierhttpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(“Bearer”, token);//awaits for response from the HTTP requestHttpResponseMessage response = await httpClient.GetAsync(api + query);//if the response is a successif (response.IsSuccessStatusCode){//I’m just setting the request status to success, this can be changed per your requirements such as deserialising into a object ectrequestStatus = “success =”;}//this is returing the request status text + the content of the request responsereturn requestStatus + await response.Content.ReadAsStringAsync();}}}}
Conclusion
After using application accounts, any application I build that needs to interact with Dynamics 365 this will be my first choice. Software vendors who provide applications which integrate with Dynamics 365 should consider providing this way of authenticating for their application. This decrease the total cost of ownership of their software as it would not require a Dynamics 365 license for the application whilst possibly making it more secure.
Image from here
Join the Capgemini Microsoft team, open roles here.
