\nAt the same time, we are releasing the developer preview of a JavaScript flavor of ADAL<\/a>, which will make it super easy for you to take advantage of Azure AD for handling sign in in your AngularJS based SPAs.<\/p>\n
Last week I visited Cory on his Web Camp TV show, where I had the opportunity of introducing ADAL JS and demonstrating it in action; you can head to the recording<\/a> if you want a quick overview.<\/a><\/p>\n In this post I will dig a bit deeper in the library and its basic usage. Remember, this is a preview and nothing is set in stone. We really want your feedback on this one \u2013 please let us know what you like and what you want us to do differently!<\/p>\n That said, without further ado\u2026<\/p>\n As usual, using ADAL JS does not require any protocol knowledge. In fact, operations here are even easier (though more tightly scoped) than with any other ADAL flavor. You just need to add a reference to the library, initialize it with the coordinates of your app, specify which routes should be protected by Azure AD \u2013 and you\u2019re good to go.<\/p>\n Let\u2019s flesh out the details. I will use our basic SPA sample<\/a> as a reference.<\/p>\n By default, applications provisioned in Azure AD are not enabled to use the OAuth2 implicit grant. In order to try the OAuth2 implicit grant preview, you need to explicitly opt in for each app you want to experiment with. In the current developer preview the process unfolds as in the following.<\/p>\n As it is customary for J S libraries, you can either include the file (adal.js) in your local Scripts library, or you can pull it in via CDN (for this preview, the minified version lives at https:\/\/secure.aadcdn.microsoftonline-p.com\/lib\/0.0.1\/js\/adal.min.js<\/a>). Either way, you\u2019ll want to pull adal.js in your main html page:<\/p>\n <\/p>\n The rest all takes place in your main app.js file, where you\u2019d normally configure your route. In our sample we use the OOB ngRoute, but in fact you don\u2019t have to stick to it. First, we need to include the ADAL module:<\/p>\n We also need to make sure that we pass the corresponding provider to the app.config:<\/p>\n Then, as we define the routes as usual, we can specify if there are some that we want to protect with Azure AD:<\/p>\n There are other ways of kicking off the authentication dance, but this is the one with the least amout of code involved.<\/p>\n Finally, the initialization proper. We have to pass to ADAL the coordinates that describe our app in Azure AD:<\/p>\n On the client, that\u2019s all you have to do. For what concerns the API backed, you just configure it in the same way in which you configure Web API with Azure AD authentication: with the OAuth bearer OWIN middleware. The only difference is that in the audience you\u2019ll need to use the clientid of the app, the same value you just passed in Init() above.<\/p>\n Hit F5. You\u2019ll land on the home view. Click on Todo list: you\u2019ll be bounced to the familiar Azure AD authentication screen. Enter your credentials, and you\u2019ll end up on the screen below.<\/p>\n \u266aTa dah!\u266a Barely 3 lines of JavaScript strategically placed, and your SPA gets to partake on one of the biggest identity systems on the planet.<\/p>\n Well, that was pretty smooth. Aren\u2019t you curious about how that happened?<\/p>\n Traditional web apps reply on roundtrips both for executing business logic and for driving the user experience. The classic way of securing those entail an initial leg where the user is shipped elsewhere via a full redirect, typically to the authority that the app trusts as identity provider. This initial leg results in a token being sent to the app. The app (or usually some form of middleware sitting in front of it) will validate the token and, upon successful verification, will issue to itself a session cookie. The session cookie will be present in all subsequent requests: the app will interpret its presence (and validity) as a sign that the request comes from an authenticated user. Rinse and repeat until the cookie expires. And once it does, the middleware will simply redirect the browser to the authority again – and the dance will continue.<\/p>\n SPAs don\u2019t work too well with the same model. The cookie can be used for securing calls to your own backed, and in fact lots of people do so; but this does not work if you want to call API on a different backend (cookies can only go to their own domain). Also, web API calls aren\u2019t too conducive of renewing cookies \u2013 when some JavaScript is trying to get data for populating an individual DIV and the session cookie it uses is expired, getting back a 302 isn\u2019t the most actionable thing. Finally, having to support cookies on your Web API is just odd: that would not help at all when the same API are invoked by a native client, forcing you to maintain multiple validation stacks and ensure that they don\u2019t step on each others\u2019 toes. ADAL JS does not use cookies, or at least not directly.<\/p>\n Just as traditional web apps and SPAs have evolved different mechanisms for managing security and user authentication, the process of buying medication<\/a> like Strattera online has also adapted to modern consumer needs. Online pharmacies have streamlined the process of purchasing medications by utilizing secure, direct platforms that bypass traditional prescription refill methods. This allows consumers to conveniently order Strattera from the comfort of their homes, ensuring privacy and ease of access much like how modern web applications manage user sessions and authentication without traditional cookies. Moreover, just as ADAL JS provides a more seamless integration without the use of cookies, online pharmacies optimize their user experience by ensuring that all transactions are secure and that patient information is protected, thereby simplifying the process of obtaining necessary medications.<\/p>\n Signing in is kind of a misnomer here, but only if you know what\u2019s really going on under the cover \u2013 and most don\u2019t need to. Rather than forcing everybody to grok what happen in the name of accuracy, we just went with the flow J<\/p>\n Signing in for ADAL JS actually means obtaining a token for your app\u2019s backend API. As simple as that.<\/p>\n Given that from Azure AD\u2019s perspective your JS frontend and your web API backend are actually different manifestations of the same app, you will be asking a token for yourself: which is exactly the semantic for an id token. We already do that in the OpenID Connect middleware, however there our goal is to deliver the token to the server side of the web app. Here we want the JavaScript frontend to obtain the token, so that it can later use it whenever it needs to invoke its own Web API.<\/p>\n Here there\u2019s how the request looks like:<\/p>\n GET https:\/\/login.windows.net\/developertenant.onmicrosoft.com\/oauth2\/authorize?response_type=id_token&client_id=aeadda0b-4350-4668-a457-359c60427122&redirect_uri=https%3A%2F%2Flocalhost%3A44326%2F&state=8f0f4eff-360f-4c50-acf0-99cf8174a58b&nonce=8b8385b9-26d3-42a1-a506-a8162bc8dc63 HTTP\/1.1<\/span><\/p>\n Notice that we are asking for an id_token, and that we do inject state and nonce for the usual security reasons.<\/p>\n The response is the interesting part:<\/p>\n HTTP\/1.1 302 Found Location: https:\/\/localhost:44326\/#id_token=eyJ0eXAiOiJKV1QiLC[SNIP]gu1OnSTN2Q2NVu3ug<\/span>&state=8f0f4eff-360f-4c50-acf0-99cf8174a58b&session_state=e4ec5227-3676-40bf-bdfe-454de9a2fdb2<\/a><\/span><\/p>\n Server: Microsoft-IIS\/8.0<\/span><\/p>\n The id_token is delivered as a fragment<\/i>, so that only the client is able to access it.<\/p>\n Now that we have the token on the client we can store it and retrieve it whenever we are about to send a request to our backed API. We\u2019ll detail how ADAL JS does it a little later.<\/p>\n Once you have a token, on the wire a call to an API looks exactly the same as what you\u2019d see from any other client type: you\u2019ll find an authorization header containing a bearer token, just like OAuth2 prescribes.<\/p>\n In this particular case, however, we know a lot about the circumstances in which the call will be made. Whereas a native client can use all sorts of classes to compose the request, here we know it\u2019s going to use what the browser (and JS in general) makes available. Thanks to that knowledge, ADAL JS can go further than any other ADAL flavor and automatically attach the right token whenever you make an API call. In fact, it can even renew it or request it ex novo contextually to the call! That\u2019s why in the sample you don\u2019t see any code referencing AuthenticationContext, AcquireToken and the like: those primitives are there but unless you want to do something custom you don\u2019t actually need to use them One of the other shortcomings of cookie based sessions lies in the fact that renewing them is kind of a pain, which leads devs to decouple the session validity from the validity of the token itself. That typically delivers a smoother experience (popping a redirect once per hour isn\u2019t fun for the user) but makes it much harder to revoke a session when something goes south.<\/p>\n In this flow we are not working with cookies, but tokens. In native applications, tokens are refreshed using refresh tokens. However here we run in a user agent, hence delivering something as autonomous as a refresh token is a dangerous proposition; not an option either. GET <\/span>https:\/\/login.windows.net\/52d4b072-9470-49fb-8721-bc3a1c9912a1\/oauth2\/authorize?response_type=id_token&client_id=e9a5a8b6-8af7-4719-9821-0deef255f68e&redirect_uri=http%3A%2F%2Flocalhost%3A49724%2F&state=064f47a8-da8d-45bc-bc58-78469dfa7434%7Ce9a5a8b6-8af7-4719-9821-0deef255f68e&prompt=none&login_hint=mario%40developertenant.onmicrosoft.com& If the session is gone (maybe somebody signed out) then we will not be able to extend the session further without user interaction, but that will be because that\u2019s what the authority wants and not for any limitation of the flow. Pretty neat, eh? The trick described above can do much more than renewing the tokens for your own Web API backend; it can be used for obtaining tokens for other Web API, too. However this time we will be requesting regular access tokens, and we\u2019ll have to specify the resourceID of the API we want. Furthermore, those API will need to support CORS.<\/p>\n Signing out is pretty much as usual. Note that we don\u2019t need to let our backend know that we\u2019re signing ouit, vigen that all session artifacts are under the JS frontend\u2019s control.<\/p>\n GET https:\/\/login.windows.net\/developertenant.onmicrosoft.com\/oauth2\/logout?post_logout_redirect_uri=https%3A%2F%2Flocalhost%3A44326%2F HTTP\/1.1<\/span><\/p>\n Now that we understand the basic flows behind ADAL JS, we can dig a bit deeper in how the library makes all that happen.<\/p>\n ADAL is exposed to your apps as an AngularJS module, \u201cadalAngular\u201d. All of the interesting logic takes place in a service, \u201cadalAuthenticationService\u201d, which surfaces selected primitives to be used at init time and from the app\u2019s controllers. The main methods and properties you\u2019ll work with are:<\/p>\n This method initializes the entire ADAL JS engine. You have seen it in action in the sample with as configOptions the only two mandatory parameters:<\/p>\n Tenant \u2013 tenantID or domain of the target Azure AD tenant .<\/p>\n clientId \u2013 client ID of the application.<\/p>\n The values passed in configOptions end up being exposed afterwards in the config<\/b> property.<\/p>\n There are many more optional parameters you can use for modifying the default behavior.<\/p>\n redirectUri \u2013 in case you want to use anything different from the root path of the application when getting back tokens.<\/p>\n postLogoutRedirectUri\u2013 in case you want to use anything different from the root path of the application when signing out.<\/p>\n localLoginUrl \u2013 this parameter allows you to specify a specific Url to be used in lieu of the default redirect to Azure AD that would take place when an unauthenticated user attempts to access a protected route. You can use that page for creating any auth experience you like, such as for example something that gives users a choice between authenticating with Azure AD (see below n how to implement that option) or with a local provider.<\/p>\n Instance \u2013 by default, ADAL JS addresses requests to login.windows.net. If you want to override that, you can enter the desired hostname here.<\/p>\n expireOffsetSeconds \u2013 this value is used to determine with much advance an access token should be considered expired. Every time ADAL fetches a token from the cache, before it it assesses whether the token is less than this value (the default is 120 secs) from expiring. If it is, ADAL triggers a renew flow before performing the call.<\/p>\n extraQueryParameter \u2013 this has the same function as its homonym in the other ADALs, it allows you to pass any extra value you want to send to Azure AD in the querystring of authorization requests.<\/p>\n Endpoints \u2013 this is a very important parameter. ADAL can always tell what token to use when you\u2019re calling your own backend, but without this property it would have no clue on how to handle other API. Endpoints is an array of couples (URL, resourceID). Every time a call to an API is made, ADAL\u2019s interceptor looks up the requested URL in endpoint, then searches the cache for a token with a corresponding resourceID. If it finds it, it uses it; otherwise, it requests a token for that resource, caches it and then uses it. Very handy!<\/p>\n This property holds the main info about the currently signed in user and signed in status. Sub-properties:<\/p>\n isAuthenticated \u2013 Boolean indicating whether there is a currently signed in user.<\/p>\n userName \u2013 UPN or email of the currently signed in user<\/p>\n profile \u2013 the claims found in the id token, decoded and exposed as properties.<\/p>\n loginError \u2013 login erros, if any.<\/p>\n Those methods can be used for driving login and logout directly, as opposed to side effects of requesting a protected route. They are pretty easy to use, all you need to do is set them up in the controller backing the view where you want to place your sign in\/out gestures:<\/p>\n ADAL JS also offers you the opportunity of handling events associated to the login outcome. That\u2019s super important for error handling. For example:<\/p>\n <\/p>\n You can take a look at the cache logic by inspecting the code. As mentioned, ADAL JS cache is based on localStorage. It allows for interesting feats, like the ability of staying signed in even if you close the browser. Below you can see a screenshot of ADAL\u2019s cache content (and what ADA JS keeps in localStorage in general).<\/p>\n VERY IMPORTANT. The use of localStorage does have security implications, given that other apps in the same domain will have access to it (kind of what happens with cookies in the default case) and it is prone to all the same attacks that localStorage have to deal with. Please exercise caution when using this feature and ensure you do all the due diligence you\u2019d normally do for protecting data in localStorage. Also, remember: this is a developer preview. That means that it should not used for anything but experimenting, given that we are still just gathering feedback\u2026 please don\u2019t use those bits with anything critical The Basics<\/h3>\n
Set up the OAuth2 Implicit grant for your test app<\/a><\/h4>\n
\n
oauth2AllowImplicitFlow<\/code> property. You will find that it is set to false<\/code>; change it to true<\/code> and save the file.<\/li>\nAdd a reference to the library<\/h4>\n
<script src=\"App\/Scripts\/adal.js\"<\/span>><\/script><\/span><\/pre>\n<\/pre>\n
Initialize<\/h4>\n
var<\/span> app = angular.module('TodoSPA'<\/span>, ['ngRoute'<\/span>,'AdalAngular'<\/span><\/span>]);<\/pre>\napp.config(['$routeProvider'<\/span>, '$httpProvider'<\/span>, 'adalAuthenticationServiceProvider'<\/span><\/span>,<\/pre>\n function<\/span> ($routeProvider, $httpProvider, adalAuthenticationServiceProvider<\/span>) {<\/pre>\n$routeProvider.when(\"\/Home\"<\/span>, {\ncontroller: \"HomeController\"<\/span>,\ntemplateUrl: \"\/App\/Views\/Home.html\"<\/span>,<\/pre>\n}).when(\"\/TodoList\"<\/span>, {\ncontroller: \"TodoListController\"<\/span>,\ntemplateUrl: \"\/App\/Views\/TodoList.html\"<\/span>,\nrequireADLogin: true<\/span>,<\/span>\n<\/pre>\nadalAuthenticationServiceProvider.init(\n{\ntenant: 'contoso.onmicrosoft.com'<\/span>,\nclientId: 'e9a5a8b6-8af7-4719-9821-0deef255f68e'<\/span>\n},\n$httpProvider\n);\n<\/pre>\nRun!<\/h4>\n
![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/10\/image_thumb3.png\" "\\"image\\"")
<\/a><\/p>\nDeep Dive<\/h3>\n
Protocol Flows<\/h4>\n
Signing In<\/h5>\n
\n<\/span>Cache-Control: no-cache, no-store
\n<\/span>Pragma: no-cache
\n<\/span>Content-Type: text\/html; charset=utf-8
\n<\/span>Expires: -1<\/span><\/p>\nCalling APIs<\/h5>\n
![\"Smile\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/10\/wlEmoticon-smile3.png\")
<\/p>\nKeeping the session alive<\/h5>\n
![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/10\/image_thumb4.png\" "\\"image\\"")
<\/a><\/p>\n
\nWe do have another option to renew tokens without perturbing the user experience AND without introducing hard to revoke session artifacts. The trick is to go back to the authority asking for a token, like we\u2019d do in the roundtrip apps scenario, but doing so in a hidden iframe<\/i>. If there is still an existing session with the authority (which might be represented by a cookie \u2013 but it is a cookie in the domain of the authority, NOT the app\u2019s) we will be able to get a new token without any UX. There is even a specific parameter, prompt=none, which lets Azure AD know that we want to get the token without a UX, and if it can\u2019t be done we want to get an error back. Here there\u2019s the request.<\/p>\n
\ndomain_hint=developertenant.onmicrosoft.com&nonce=e8aba94f-8cd5-497b-bf9b-180de4a8bcf4<\/span><\/a> HTTP\/1.1
\nHost: login.windows-ppe.net<\/span><\/p>\n ADAL JS does all this behind the scenes for you. More details later.<\/p>\nGetting Tokens for Other Services<\/h5>\n
Signing out<\/h5>\n
Components<\/h4>\n
\nIt does not have to be that way, and in fact you could use the lower layer in any other JS stack if you\u2019d so choose, but for this preview if you use AngularJS you\u2019ll have the best experience.<\/p>\nInit(configOptions, httpProvider)<\/h5>\n
UserInfo<\/h5>\n
login and logOut<\/h5>\n
app.controller('HomeController'<\/span>, ['$scope'<\/span>, 'adalAuthenticationService'<\/span>,'$location'<\/span>,<\/pre>\nfunction<\/span> ($scope, adalAuthenticationService, $location) {\n$scope.Login = function<\/span> () {\nadalAuthenticationService.login();\n};\n$scope.Logout = function<\/span> () {\nadalAuthenticationService.logOut();\n};\n}]);\n<\/pre>\n$On<\/h5>\n
$scope.$on(\"adal:loginSuccess\"<\/span>, function<\/span> () {\n $scope.testMessage = \"loginSuccess\"<\/span>;\n });\n\n $scope.$on(\"adal:loginFailure\"<\/span>, function<\/span> () {\n $scope.testMessage = \"loginFailure\"<\/span>;\n $location.path(\"\/login\"<\/span>);\n });\n<\/pre>\nCache<\/h4>\n
<\/p>\n
![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/10\/image_thumb5.png\" "\\"image\\"")
<\/a><\/p>\n