In Dynamic 365 for Finance and Operations the service endpoints are deployed automatically upon build, without the need of any additional setup or configuration we used to do with legacy AIF services. However, in the current D365FO service endpoints, we do not have many of the configuration possibilities which were provided by WCF configuration and inbound/outbound port management before.
Azure API management service is an Azure service that provides a highly configurable front end for many sorts of Azure and 3rd party web api services, as well as for our D365FO service endpoints.
Adding D365FO API services to Azure API management brings up many advantages. Some of those are :
- You will be able to hide your D365FO address from the subscribers of your API service. They will see the API management endpoint URL instead.
- You can add additional security to your service using API management’s subscription keys, encryption, ddos attack protection and many other security features.
- You can easily add quotas, limits and other intelligent access policies using API management’s .NET based policy scripts.
- You can setup cloud based JSON/XML conversions for your older SOAP services
- You can log access to your service in detail, also using Azure application insights, track service health, track issues and get notifications from Azure for important events.
- You can organize all your organization’s APIs (web apis, D365CE apis, D365FO apis, 3rd party apis) together in one place and one address.
- You can use advanced caching for your services.
How to add a D365FO service endpoint to Azure API Management
Unfortunately, in the time of writing, it is not a straightforward process, like clicking a button on D365FO UI and adding your service directly to API management. So we need to struggle a bit with some configurations to be able to achieve this..
To begin with, we need a D365FO API service for testing in API management service. In this example I will use the same service I have created for my previous blog post, the visit schedule service in How to connect a Native Android Application to Dynamics 365 FO. You can download and install the D365FO project file for this service from the link below :
Then, create an API management instance from Azure portal. The name you give to your management instance will be the used as the url prefix to access all your API services like “https://<managemeninstancename>.azure-api.net/<apisuffix>“. After the service is created (will take a long time) open it in Azure portal, go to products tab and create a new Product. This step is optional for testing, but it is a good practice to use a product for all D365FO services to organize them together from the beginning:
The API manager will create a default subscription for that product in the subscriptions tab with all the needed keys.
Then we need to setup an Azure AD app registration ID for the API manager to be able to connect the D365FO API service using “Azure Active Directory>App registration” tab in Azure portal.
At that point you have two possibilities to authenticate API manager endpoint for D365FO service connection:
Using Authorization Code:
In this option the API service client needs to login Azure AAD with login credentials (and use MFA if applicable) to receive a valid token for the connection. The API service client needs to use an AAD login API like MSAL or ADAL and display a login screen to user for entering Azure AD credentials. This option is the most secure way to do it and in this article I will be demonstrating this one.
Using Server 2 Server connection with Client credentials :
This is a rather new option which was not available before in D365FO, and allows you to login to a D365FO service without the need to collect user credentials from Azure AD. In that case you create a client secret and setup an Application type of permission for your registered app (will get into details later), and you need to add a definition for your app id in D365FO form “System Administration>Setup>Azure Active Directory Applications”. Then you can login to the D365FO service only using security options provided by API management, or directly without any security involved. Remember this is not a secure way to connect your D365FO API and may involve changing some of your directory policies.
To continue, register an application ID for our API management to access D365FO service with Azure AAD authorization, as described in the link below :
here choose “Accounts in any organizational directory” in the creation of your app registration and note your application (client) ID GUID after the creation. We will use that later. Go to API permissions tab from here and add the following permission to your app registration (If you want to test Server 2 Server authentication with client credentials, add application permissions too):
If you plan to test Server 2 Server connection with client credentials as well, go to Certificates & Secrets tab and add a new client secret. Note this value to be used later :
Go to overview tab and open endpoints window, to copy some values from here later.
Leave this window open, we are not finished with it yet, and open another azure portal window with your API Management setup. Go to the Security>Oauth 2.0 tab here and add a new OAuth2 service. Fill the values as shown below :
- Name : any connection name
- Client registration page URL : copy the authorization endpoint address from app registrations
- Authorization : Authorization code and Client credentials (optional, if you also want to test it)
- Authorization end point : copy from app registration endpoints
- Authorization request method : GET
- Token endpoint URL : copy from app registration endpoints
- Client authentication methods : in the body
- Access token sending method : Authorization header
- Default scope : Your D365FO base URL, followed by a “/.default” suffix
- Client credentials : Copy the values you have noted before in app registration step
- Resource owner credentials : leave all blank
Save your settings and go to the APIs tab to add our D365FO service endpoint. Here you have many options for adding an API to your API management. You can add logic apps, azure functions as well as WSDL and Open API documents. Unfortunately there is in the time of writing no option for us to generate an OpenAPI specification document for our D365FO service endpoints. So we can either write the OpenAPI document manually ourselves or use the Blank API option here. Click on the Blank API button and add specifications for your service endpoint. For the visit schedule test service, add the following URL suffix to your base D365FO url : “/api/services/AndroidTests/AndVisitSchedule”
The “API URL suffix” field here is for the Azure API management service URL itself, and you are allowed change this anytime you like. Do not forget to add this API to the D365 product we have created before, and save your changes. After save is complete, open the settings tab for your API and from here configure OAuth 2.0 authorization as shown below :
Here in the setting page we can also disable the requirement for subscription keys. For this test, we will not going to do that and show how you can add extra security using subscription keys.
Now lets add our service operation. The visit schedule demo service has two service operations. Here we add the “getNewTasks” operation to the API management service :
It is also nice to give a tag for d365 service operations because we can use this tag for filtering metrics and logs later. Leave the rest empty and save the operation.
Is that all of it? Is our service ready for testing now? No, not yet!…
Now go back to the App registration page in your Azure AAD and in the Authentication tab add the following value with type “Web” in your Redirect URIs (as well as suggested redirect URLs for Web) : “https://<yourapimanagementname>.portal.azure-api.net/docs/services/<youroauth20serviceregistrationname>/console/oauth2/authorizationcode/callback”
The API management name is simply the same name prefix which is used in your API management URLs. The oauth service registration name is the name of the setting you used in the previous step for creating oauth2 registration for the API management. If you do not include this setting, you get an error on the AAD authorization used by the Developer Portal Test page of API management.
Now in the end, we are ready to test.
First create some demo records in visit scheduling to be picked up by the service. Open the visit scheduler form and enter some records:
Now go back to the API management page in Azure portal, and open “Developer portal” from the buttons in the toolbar. Here click APIs and the click on the API you have just created. Here you can run your operation and copy the code blocks needed to call the service in different programming languages. Click on your operation and click “Try it” to open the test page.
Here you need to define the authorization and the Request body. The rest you can leave as default since we did not create more than the default subscription. Click on the Authorization combo and select “Authorization code”. follow the steps in the popup windows if you need to authorize in AAD. The token received from AAD after that operation will be automatically added to request headers.
On the request body, we need to fill the parameters to call our service in JSON format. We have only one parameter, which is “_worker”, so add a JSON value for the worker id (the worker id we created demo data for) as shown above. Leave the rest of the values in the screen and hit “Send” and Voila!. If everything is correctly set, you will see the results coming from the service as shown below :
See that we can also trace the service request and see the steps involved in calling the service from the Trace tab here.
And what about testing the API management frontend service directly using a 3rd party application? To achieve this, you need the subscription keys that are created for your product in Api management (for product D365). Go to the subscriptions tab and copy the key value from the primary key of your product’s default subscription (Or be lazy and copy it from the trace window for the previous test). Then use your favorite REST client, here I will use PostMan, and setup a call to your API management operation frontend URL, like shown below.
Open the Headers tab of the request and add a header with a key of “
Ocp-Apim-Subscription-Key”. For header value, paste the subscription key you have copied. Now we also need to setup an AAD authorization to be able to acquire a token and call our service. PostMan easily arranges that for you. Go to the authorization tab and select OAuth 2.0. Click “GetNewAccessToken” and from the popup select Grant Type of “Authorization Code”. Fill in everything just the same as you have done in the API management OAuth2 setting, for the CallBack URL, just select one of the redirect URLs you setup for your AAD app registration. Click Request button and follow the steps for AAD authorization. Once finished, a token will be shown to you, click “Use token” on the bottom and you are done.
Now before testing the visit schedule service again, you may want to create some new demo data or reset the visit schedule staging by clicking “Re-initialize” in the D365FO visit schedule form. Otherwise you will get empty results.
After that is done, go back to the postman window and click “Send”. You will see the results coming (again if everything is setup correctly) :
And if you go back to your API management dashboard, you can directly see the metrics and request counts for the service operation you are testing now. Cool isn’t it? :