Microsoft Dynamics CRM OAuth, OData and Web API Overview

 

This series of blog posts demonstrates how to get a third-party application communicating with Microsoft Dynamics CRM 2016 online using the Web API. After reading all blog posts in this series the reader will be able to set up a web application that performs create, read, update and delete operations on Microsoft Dynamics CRM using the Web API endpoint.

It is important to know how to use the Web API Endpoint as the Dynamics CRM 2011 endpoints will be deprecated in the future according to Microsoft.

The Web API endpoint is easy to use from within Dynamics CRM via plugins, custom workflow activities or JavaScript. Using the Web API endpoint from a third-party website, for example a portal, is complex because authorisation using the OAuth protocol is required. This series of blog posts includes a walkthrough of using the OAuth protocol to authenticate to the Dynamics CRM Web API.

Blogs in this Series

This first blog post Microsoft Dynamics CRM OAuth, OData and Web API gives a brief overview of what OAuth, OData and Web API are and how they can be used with Microsoft Dynamics CRM.

The second article Registering a Third-Party Application with Microsoft Azure Active Directory demonstrates how to add a third-party application to Microsoft Azure Active Directory and assign Microsoft Dynamics CRM read/write permissions to the third-party application.

The third article Testing Microsoft Dynamics CRM Web API with Postman validates the third-party application can communicate with Microsoft CRM Dynamics and validates the third-party application has been configured correctly in Microsoft Azure Active Directory correctly.

The fourth article Microsoft Dynamics CRM OAuth examples in a JQuery Web Application walks through code for a JQuery Web Application that uses OAuth to generate an access token that can be used in Microsoft Dynamics CRM Web API OData messages.

The Fifth article Microsoft Dynamics CRM Web API Create, Read, Update and Delete examples in a JQuery Web Application expands on the fourth article and Walks through code for a JQuery Web Application that performs Create, Read, Update and Delete operations on the Microsoft CRM Dynamics Account entity.

OAuth

The OAuth Website describes OAuth as an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications. The OAuth 2 Specification refers to 4 roles which are summarised and related back to this blog series below.

Resource Owner: The owner of a resource. Throughout this blog series, this will always be the person who is using the third-party application.

Resource Server: The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens. Throughout this blog series, the resource server will be the Microsoft Dynamics CRM Instance that we are performing CRUD operations against.

Client: The application that accesses the resource owner’s protected resources from the resource server. The client can be any application: a native mobile application, windows desktop application, a Web API or a Web Site. Throughout this blog series, the third-party web application will be the client.

Authorization Server: This is the server that issues access tokens to the client after the resource owner has been authorized by entering their correct credentials into the authorization server’s login screen. Throughout this blog series, the Authorization Server will be Microsoft Azure Active Directory.

There is one additional important piece of terminology and that is protected resource. Throughout this blog series, a protected resource is data that the client is performing CRUD operations on, on behalf of the resource owner, eg. the third-party application updating accounts.

OAuth Flow The below generic model of the OAuth protocol flow is from OAuth Specification-> Process Flow web page.

oauth flow - dynamics crm web api

An example of the above generic OAuth flow is:

  • Bob signs into the client (third-party application) using his Microsoft login details the client (third-party application) is redirect to the authorization servers (Microsoft Azure Active Directory’s) login screen. Then the resource owner (Bob) enters his credentials and consents to the client (third-party application) accessing and or modifying the resource owners protected resources (Microsoft Dynamics CRM data)
  • The authorization server (Microsoft Azure Active Directory’s) redirects to the client (third-party application) with an access code in the query string.
  • The client (third-party application) requests an access token from the authorization server (Microsoft Azure Active Directory) using the access code from step (B).
  • The authorization server (Microsoft Azure Active Directory) returns an access token as well as a refresh token and an expiry time to the client (third-party application). The refresh token can be used to generate a new access token when the original access token expires.
  • The access token is embedding into a request header to the Resource Server (Microsoft Dynamics CRM) when querying accounts (or creating, updating and deleting accounts).
  • The resource server (Microsoft Dynamics CRM) responds with the requested protected resource (account data).

Please note this OAuth information is copied or paraphrased from the above links

OData/Web API

According to OData.org, OData is an OASIS standard that defines a set of best practices for building and consuming RESTful APIs. OData helps you focus on your business logic while building RESTful APIs without having to worry about the various approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats query options, etc.

ASP.NET Web API is a framework for building web APIs on top of the .NET Framework. ASP.NET Web API can expose a OData enabled web service. The Dynamics CRM Web API endpoint is an OData enabled web service that allows Dynamics CRM data to be created, read, updated and deleted.

Summary

The first part of this blog series outlined a road map for future blog posts and gave theoretical description of OAuth and OData. The next blog posts in this series will be hands on and more relevant to Dynamics CRM.