Monday, June 19, 2017

Using Postman and the Dynamics 365 Web API

All applications performing external requests to the Dynamics 365 (online) web API first need to be registered with Microsoft Azure Active Directory to be able to authenticate using OAuth. The same also applies to Postman – for those of you who don’t know Postman, it is a pretty handy utility which allows you to perform for example REST calls without the need to write code.

For a detailed discussion about registering apps in Azure see Walkthrough: Register a Dynamics 365 app with Azure Active Directory (it still uses screenshots from the old Azure Portal https://manage.windowsazure.com but overall the steps are still valid).

To register Postman as an external application I followed these steps:
  • Select the Azure Active Directory  in which you need to register your app (Remember you can link multiple Azure Active Directories to a single Azure subscription)
  • When using Postman, you can register a native app and provide a Redirect URI - enter a value specific to your application e.g. http://localhost/postmand365app
  • Once you have registered your application, AAD will assign your application a unique client identifier (this is the ApplicationId which is listed the screenshot below. )

  • Create a secret key for your Azure app registration – make sure that you copy the key value since it will only be visible on the first save.
  • Give your application the necessary rights to connect through to CRM. Since you don’t want to show the oAuth consent screen, you want to grant the application the necessary consent. As an administrator, you can  consent to an application's delegated permissions on behalf of all the users in your tenant by clicking on the “Grant permissions” button.


If you did not correctly complete the previous steps, you will probably see some errors around invalid grants later on as shown in the next screenshot.



You have now completed all the necessary preparation  - now you need to construct the POST request to retrieve the bearer token which needs to be used in subsequent requests to Dynamics 365. You will need to do a request to https://login.microsoftonline.com/{tenantid}/oauth2/token – where tenantid is the Azure Active Directory Tenant Id.  You can retrieve this in the Azure Portal, if you click on the Help icon in the upper right and then choose 'Show Diagnostics' – this will show the the diagnostic JSON which also contains the tenantid.
  • Header:
    • Cache-control: no-cache
    • Content-type: application/x-www-form-urlencoded
  • Body
    • client_id: the ApplicationId you saw in Azure AD
    • resource: https://.crm.dynamics.com (CRM tenant url)
    • username and password:  ... 
    • grant_type: password
    • client_secret: the secret key value that you got from Azure app registration
I use Postman variables (see Using variables inside postman and collection runner) for a number of these values e.g. username, password,etc … as visible in the screenshot below. To see if everything works correctly, click on send, in the response you will see an access token that you need to use in calls to the CRM Web API.


To make this easy to use add the code snippet below to the Tests tab – this will save the access_token returned to an environment variable.
var json = JSON.parse(responseBody);
postman.setEnvironmentVariable("bearerToken", json.access_token);
To validate that this worked correctly click on the “Eye” icon in the upper right corner and you will see a “bearertoken” environment variable which can be used for subsequent requests.


To make a web request using this token using the header values below -  this will continue to work until the token expires and then you simple get a new one, by executing the request to https://login.microsoftonline.com/{tenantid}/oauth2/token and you will be able to run your requests directly within Postman.