{"id":3245,"date":"2015-04-06T07:00:11","date_gmt":"2015-04-06T14:00:11","guid":{"rendered":"http:\/\/www.cloudidentity.com\/blog\/?p=3245"},"modified":"2015-04-06T13:33:19","modified_gmt":"2015-04-06T20:33:19","slug":"adal-plugin-for-apache-cordova-deep-dive","status":"publish","type":"post","link":"https:\/\/www.cloudidentity.com\/blog\/2015\/04\/06\/adal-plugin-for-apache-cordova-deep-dive\/","title":{"rendered":"ADAL Plugin for Apache Cordova: Deep Dive"},"content":{"rendered":"

I am super happy to finally be able to talk about this! Today our friends in MS open Tech are releasing<\/a> the first developer preview of an Apache Cordova plugin for ADAL<\/a>, the result of few months of merry collaboration between out teams. This plugin will be yet another arrow in your developer quiver for adding the power of Azure AD to your multi-platform applications \u2013 namely, the ones targeting iOS, Android, Windows Store and Windows Phone. You can find the announcement posts here<\/a> and here<\/a>. And if you want to get started quickly, instead of sifting through all my words salad below, head straight to the sample repo<\/a> and follow the detailed readme<\/a>! In this post I am going to dig a bit deeper on the role that the plugin plays in the ADAL franchise, mention intended usage and take a peek under the hood of the plugin itself.<\/p>\n

No compromises: JavaScript apps with the power of native ADALs<\/h2>\n

\"image\"<\/a><\/p>\n

Since we announced ADAL JS<\/a>, we had a constant stream of questions about using it in Cordova applications: how to do it, why it was not optimized for that use case, and so on. Technically it is<\/em> possible to use ADAL JS in Cordova apps \u2013 I know of people who do it. However ADAL JS is designed to operate in a different environment, SPA apps coming from a\u00a0 server, and assumes constraints that are simply not present in Cordova apps: browser sandboxing, absence of refresh token in the implicit flow, and so on. The Cordova plugin for ADAL does not have to cope with such limitations, and it grants you far more access to the advanced authentication capabilities of the devices themselves. How? Perhaps I should start from getting on the same page on what Cordova is. Quoting from its about page<\/a>:<\/p>\n

Apache Cordova is a set of device APIs that allow a mobile app developer to access native device function such as the camera or accelerometer from JavaScript. Combined with a UI framework such as jQuery Mobile or Dojo Mobile or Sencha Touch, this allows a smartphone app to be developed with just HTML, CSS, and JavaScript. When using the Cordova APIs, an app can be built without any native code (Java, Objective-C, etc) from the app developer. Instead, web technologies are used, and they are hosted in the app itself locally (generally not on a remote http server). And because these JavaScript APIs are consistent across multiple device platforms and built on web standards, the app should be portable to other device platforms with minimal to no changes.<\/p><\/blockquote>\n

That is a very, very neat trick. As our first sample<\/a> shows, it is amazingly simple to whip together one app \u2013 and run it on many different platforms without a single change<\/em>. Of course our sample is a toy, as samples demonstrating API usage ought to be \u2013 IRL you\u2019d likely at least add some CSS to comply to the look & feel of the targeted platform. But even taking that into account, I am amazed by how succinct the app code turns out to be. Cordova achieves its tricks by exposing native platform capabilities by plugins<\/em>: JavaScript fa\u00e7ades which route calls to fragments of native code \u2013 native code that the plugin must supply for each of the platforms it wants to support. That is also how the ADAL plugin came to be: we decided a JavaScript API to use for exposing the most basic ADAL capabilities, then the valiant developers at MS open Tech created a bridge between that and the native ADALs on iOS, Android and .NET. (specifically, the two Windows Runtime Components in the ADAL\u00a0 .NET NuGet targeting Windows Store and Windows Phone 8.1 store apps). Concretely: say that you write a Cordova app and you deploy it to an iOS device, real or emulated. When in your JavaScript you invoke one of the ADAL Cordova plugin methods, say the classic acquireTokenAsyc<\/strong><\/span>, what actually happens is that the parameters will be dispatched down and the logic will be executed by the Objective-C flavor of ADAL: the cached tokens will be looked up from the Keychain, for example. Take the same application, and deploy it to a Windows device: the exact same JavaScript call will end up being executed by the corresponding .winmd component, and the tokens will be looked up from the Windows Store isolated storage. None of that would be possible with ADAL JS, of course: the storage on the actual device would be completely unreachable. The same holds for any other capability you get when you use the native ADALs.<\/p>\n

ADALs\u2019 Rosetta Stone<\/h2>\n

This isn\u2019t the first time we work on an ADAL deliverable that can target multiple targets at once: ADAL .NET 3.0 preview<\/a> uses PCLs and Xamarin technology to target the same platforms discussed here. Apart from the obvious audience difference between the two libraries (one is aimed at C# developers, the other at JavaScript ones) the main characteristic that sets those apart is how deep they need to drill in the platform layers to achieve their goals. For ADAL .NET, it\u2019s the .NET Framework itself that is now available on every platform. The differences between platforms do exist, and we do need to take them into account in our programming model, but those all still live at the .NET level: we do need to change the component that shows the web authentication experience on every platform, but on every platform there\u2019s a .NET API for it. Those differences surface all the way to you, the application developer: your Visual Studio solution typically has projects for each platform, where you write platform specific code (though that\u2019s still .NET). That basically means that we are only limited by what makes sense for the target platform, but as a baseline we can expose whatever is in ADAL .NET. In ADAL for Cordova things are different. The JavaScript layer is just a fa\u00e7ade and all the hard work is delegated to actual platform bits. We can only execute on platforms where we have an ADAL flavor available. For example: Cordova can run on Ubuntu, but we don\u2019t have an ADAL that would run natively on it. That has two main consequences:<\/p>\n

    \n
  1. The JavaScript fa\u00e7ade we expose must utilize features that are available on ALL of the ADAL libraries used by the plugin.\n
      \n
    1. Corollary: if there are differences in the way in which ADALs on different platforms handle things, the plugin should try to normalize those as much as possible<\/li>\n<\/ol>\n<\/li>\n
    2. If there are platform specific features that MUST be surfaced to support mandatory functionalities, they have to be done in ways that won\u2019t interfere with the platform-neutral programming model<\/li>\n<\/ol>\n

      That\u2019s quite a tall order! To avoid the analysis paralysis that was very likely to ensue, we deliberately kept things very simple:<\/p>\n