![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2013\/04\/image27.png\" "\\"image\\"")
<\/a><\/p>\nI have been longing to publish this post for a looong time As much as I am excited about the endpoints, it\u2019s the AAL for Windows Store announcement that is making my heart racing: the DevEx team has been nurturing this baby bird for a long time, and it\u2019s finally time to let it fly.<\/p>\n This walkthrough<\/a> and this sample<\/a> show you how to use AAL for Windows Store to add authentication capabilities to your modern Windows applications and secure calls to a Web API project. Head there to learn how to use the library, it\u2019s easy!<\/p>\n In this post I will go deeper (much deeper) in the library features and share with you some design considerations behind the choices we made. I like to think that we really took advantage of what the new Windows Runtime has to offer here, but you be the judge! This is not required reading, come along for the ride only if you are very curious about it.<\/p>\n If you are new to AAL, you might want to take a look at the intro post here<\/a>: but in brief, the Windows Azure Authentication Library (AAL) makes it very easy for developers to add to their client<\/strong> applications the logic for authenticating users to Windows Azure Active Directory, and obtain access tokens for securing API calls<\/em>.\u00a0 No deep protocol expertise required!<\/p>\n Here there\u2019s the laundry list of the main features in AAL for Windows Store:<\/p>\n I am definitely biased, but that sounds pretty exciting to me\u2026 AAL for Windows Store is not our first foray in the client authentication space. We already have a preview of AAL<\/a> out, designed to work with client applications written with .NET 4.0 and up: that includes both apps with user interaction and server-side apps operating in a client role (e.g. middle tiers calling other services). The developer passes as parameters what he or she knows about the scenario, library itself picks up which protocols to use to make authentication happen. As mentioned, AAL for Windows Store tries to solve about the same class of problems tackled by AAL .NET. Here there\u2019s a short excerpt from the original announcement, describing the basic scenario from the PoV of the developer (that would be you! AAL offers you a programming model that has counterparts for all those concepts, interlinked by the same functional relationships. In short, for Windows Store apps you implement the scenario following those 3 steps:<\/p>\n For once, I am not oversimplifying: that is exactly what happens. Here there\u2019s some C# code implementing the sequence, in the case in which the target resource is a REST service:<\/p>\n 1:<\/span> AuthenticationContext authenticationContext =<\/p>\n new<\/span> AuthenticationContext(“https:\/\/login.windows.net\/treyresearch1.onmicrosoft.com”<\/span>);<\/p>\n <\/p>\n 2:<\/span> AuthenticationResult result =<\/p>\n await authenticationContext.AcquireTokenAsync(\u201chttp:\/\/myapps\/quotesapp<\/a>\u201d<\/span>,<\/p>\n “2b8606b7-6bad-4e8b-ac3c-1356aca8ab0e”<\/span>);<\/p>\n <\/p>\n <\/p>\n 4:<\/span> httpClient.DefaultRequestHeaders.Authorization =<\/p>\n new<\/span> AuthenticationHeaderValue(“Bearer”<\/span>, result.AccessToken);<\/p>\n <\/p>\n 5:<\/span> HttpResponseMessageresponse =<\/p>\n await httpClient.GetAsync(https:\/\/poorsmanas.azurewebsites.net\/api\/InspiringQuotes<\/a><\/span>);<\/p>\n <\/p>\n<\/div>\n<\/div>\n <\/p>\n Please note, AAL is actually used just in the first 2 lines: the rest shows how to use the resulting token to call a REST service, all standard .NET code. Let\u2019s see what happens in a bit more detail, line by line.<\/p>\n Assuming that the authentication took place successfully<\/li>\n<\/ol>\n<\/li>\n \u2026and that\u2019s all you need to do! The AAL developer surface is really reduced to the essential, however there is a bit more to it than the absolute basic scenario described above. In the fullness of time we\u2019ll have a complete MSDN reference, but for the time being here there\u2019s a quick glance at the main primitives.<\/p>\n AuthenticationContext is the proxy of your Windows Azure AD tenant; it is the primitive you use every time you need your tenant to do something for you. In some sense, AuthenticationContext *is* AAL. Here there\u2019s some more details on how it works.<\/p>\n The code snippet above showed the main way of constructing an AuthenticationContext: you pass the complete URL of your Windows Azure AD tenant. In the future we will offer some kind of resource-driven discovery mechanism, but for the time being the explicit, full URL is required at construction time. Also note: if you pass a string of a format different from the login.windows.net\/<tenant> one, AAL validation of the tenant URL template will fail: that is for preventing redirect attacks in case you have dynamic logic that determines the tenant\u2019s URL. There is an overload of the constructor which allows you to turn validation off, should you need to do so for development purposes.<\/p>\n IMPORTANT. Whereas AAL .NET works with both ACS2.0 namespaces and Windows Azure AD tenants, AAL for Windows Store works only with Windows Azure AD tenants<\/em>. You already encountered the simplest form of AcquireTokenAsync:<\/p>\n <\/p>\n<\/div>\n This overload requires you to pass (hence know) the URI and the ID with which the Windows Azure AD knows the target resource and your client application, respectively.<\/p>\n If you know how the OAuth2 code grant flow you might be wondering what return URI is used, given that none is being passed as a parameter: well, in this case we use the URI assigned to the app by the Windows Runtime itself, the one of the form ms-app\/\/<SID><\/strong>. You\u2019ll read more about this in the section on Windows Store features; here I\u2019ll just say that the use of such URI will cause the WebAuthenticationBroker used during authentication to operate in \u201cSSO mode\u201d.<\/p>\n AcquireTokenAsync has another overload, taking far more parameters:<\/p>\n IAsyncOperation<AuthenticationResult> AcquireTokenAsync(string<\/span> resource, string<\/span> clientId,<\/p>\n string<\/span> redirectUri, string<\/span> loginHint, string<\/span> extraQueryParameters);<\/p>\n <\/p>\n<\/div>\n The first two parameters are the same as the ones in the first overload.<\/p>\n redirectUri<\/strong> allows you to specify a return URI different from the one assigned to the client by the Windows Runtime. There are multiple reasons for which you might want to do this: the entry representing the client app in Windows Azure AD might use an arbitrary value; you might want to opt out from WebAuthenticationBroker\u2019s SSO mode for this call ; and so on.<\/p>\n loginHint<\/strong> allows you to specify the username (e.g. adam@treyresearch1.onmicrosoft.com<\/a>) of the user you want to use for this specific authentication operation. The value of loginHint will be used to filter the token cache entries, selecting only the ones that match; if no cache entries for the username and the resource exist, the loginHint value is used for initializing the username textbox in the authentication dialog.<\/p>\n extraQueryParameters <\/strong>is there for giving you more latitude. The Windows Azure AD authorization server might accept more parameters in the future, and we don\u2019t want AcquireTokenAsync to get too long. Talking in OAuth2 terms, extraQueryParameter can be used for adding whatever extra info you want to send with the token request to the authorization endpoint.<\/p>\n To be completely transparent, personally I am not very happy of having just 2 overloads: I would have wanted to have at least another one taking resource, client id and an arbitrary return URL\u2026 but I lost that battle By default, successful invocations of AcquireTokenAsync result in the storing in a persistent cache of the requested token. AAL for Windows Store comes equipped with such persistent cache out of the box: you can find more details about that later in the post.<\/p>\n If you need to customize the caching logic, you can write your own cache (implementing the ITokenCache<\/strong> interface) and use it instead of the default one: all you need to do is to create an instance of your custom class and assign it to the TokenCache property.<\/p>\n If you want to get rid of caching altogether, all you need to do is assigning TokenCache to null.<\/p>\n IAsyncOperation<AuthenticationResult> AcquireTokenByRefreshTokenAsync(<\/p>\n string<\/span> refreshToken, string<\/span> clientId);<\/p>\n<\/div>\n All token acquisition operations result in an AuthenticationResult <\/strong>instance. Its purpose is to carry to your code the outcome of the authentication, so that you can make use of it: that typically materializes as extracting access tokens to be used in your service invocations, or examining error info if something went wrong.<\/p>\n Here there\u2019s the full list of public members:<\/p>\n Communicates the outcome of the authentication operation. Possible values, from the enum AuthenticationStatus, are Succeeded<\/strong> and Failed<\/strong>.<\/p>\n Upon successful authentication (or positive cache hit) this property holds the bits of the token intended to be used for the target resource.<\/p>\n This value indicates the time at which the token will expire.<\/p>\n If emitted by the authentication operation, this property returns a token that can be sued to refresh the access token without having to prompt the user for credentials.<\/p>\n In case of error those two properties surface details about the issue, so that it can be dealt with appropriately. Returning errors in the status makes error handling in asynchronous situations easier than through classic exceptions; that is especially evident when working in JavaScript.<\/p>\n The Windows Runtime API, coupled with the Windows Store apps \u201csandboxing\u201d system, offers an extremely powerful platform to build on. Here there\u2019s a list of the areas in which AAL takes advantage of Windows Runtime specific features to help you handling authentication as smoothly as possible.<\/p>\n There are many languages you can choose from when it comes to developing Windows Store applications: C#, JavaScript\/HTML5, C++\u2026 we wanted to make sure you retain that freedom when you use AAL.<\/p>\n As its .NET counterpart, AAL for Windows Store is a library meant to live in-process with your application. However, AAL for Windows Store does not <\/em>come as an assembly\/DLL: that would constrain its usage to Windows Store apps written in C# and VB. You can head to MSDN for a more accurate description, but in super-short: a Windows Runtime Component is a reusable library, written in either C# or C++, which takes advantage of the language projection mechanisms of the Windows Runtime. The basic idea is that if your library exposes only Windows Runtime types, and it is packaged appropriately, then your classes can be transparently projected in the syntax of each of the languages supported for Windows Store apps development. In our case, that means that with a single library we can enable both C# and JS\/HTML5 based apps to take advantage of Windows Azure AD. That\u2019s pretty sweet! P.S: in theory the library should also work for Windows Store apps written in C++\/CX. However at packaging time the NuGet support for distributing Windows Runtime Components did not cover C++ project types. If you really want to experiment with that you can get the NuGet package and extract the WINMD by hand, however you should know that the scenario is untested. Please let us know if you use C++ a lot for your business Windows Store apps!<\/p>\n AAL for .NET hosts the authentication experience in a dialog containing a WebBrowser control. With AAL for Windows Store, however, we did not need to build such dialog: the Windows Runtime already offers a specific API providing a surface for rendering Web content at authentication time. That API is exposed through the WebAuthenticationBroker<\/a> class.<\/p>\n The WebAuthenticationBroker (can I call it WAB from now on? it\u2019s really long to type Used directly, the WAB requires the developer to provide in input protocol-specific information. For example, if you want to use it for driving an OAuth2 code grant flow you\u2019d have to construct the exact URL containing the request for the authorization endpoint; and once you\u2019d get back the code, you\u2019d be responsible to parte the request to retrieve it and use it to hit the token endpoint with the right message format.<\/p>\n AAL for Windows Store fully wraps the WAB, presenting you with an object model that is only concerned with the actors coming into play in your solution (your client, the windows azure AD tenant, the resource you want to access)\u00a0 and making all of the necessary calls on your behalf. Hence, in theory you would not even need to know that the WAB is the API used to render the auth UI. Authentication cookies management in Windows Store is less straightforward than on the classic desktop, and that influences how AAL for Windows Store operates.<\/p>\n When you use AcquireTokenAsync without specifying a return URL, AAL invokes the WAB in \u201cSSO mode<\/a>\u201d. In a nutshell that means that the WAB will expect the auth provider to deliver its results by redirecting toward a special URI of the form ms-app:\/\/<SID> where the SID is the package ID of the Windows Store application. In return for this proof of tight coupling between the authority and the app itself, the WAB will grant access to a persistent cookie jar shared by all SSO mode applications: that will allow taking advantage of information associated to previous runs (such as persistent cookies) and occasionally achieve the SSO that gives the name to this mode. If App1 authenticated with Authority A in SSO mode, and A dropped a persistent cookie to represent an ongoing session, App2 opening the WAB in SSO mode will be able to authenticate with A by leveraging the existing cookie.<\/p>\n When you use AcquireTokenAsync specifying an arbitrary return URL, that value is passed straight to the WAB. And then the WAB operates on an arbitrary return URL, it assumes a \u201clow trust\u201d connection with the provider and constrains execution against a brand-new empty cookie jar. That is for protecting the user from low-trust apps, which could leverage existing cookies to silently access data on the web sites the user is authenticated with.<\/p>\n That\u2019s pretty handy! But, say, what if you want to take advantage of SSO mode (which you automatically get with the simplest AcquireTokenAsync) while also specifying the login_hint for the current user? Easy. You can use the longer AcquireTokenAsync overload, and pass as return URI the address that the WAB would use if you would not specify any. You can obtain that programmatically by calling WebAuthenticationBroker.GetCurrentApplicationCallbackUri()<\/strong>.<\/p>\n Windows Store applications are executed in a sandboxed environment, which limits what they can do with system resources to the things that the user explicitly allowed at install time.<\/p>\n Being Windows Azure AD meant to enable business scenarios, the use of AAL for facilitating authentication flows will more often than not entail access to enterprise resources and capabilities such as<\/p>\n Windows Store applications can do none of those things, unless you explicitly enable them in the capabilities section of the Package.appxmanifest file. And given that it\u2019s really impossible for us to know in advance what will be required (that\u2019s really driven by the Windows Azure AD tenant: is it federated with a local ADFS2 instance? Does it require certificate based auth?) and even if you\u2019d know at a given time, the authenticating authority can change policy much faster than your app\u2019s install\/update lifecycle.<\/p>\n For those reasons, if you don\u2019t turn on those capabilities in your manifest AAL might not work as expected. This is another area for which we are eager to get your feedback: is it acceptable for your business and enterprise apps to request those capabilities? Let us know about your scenarios, it will be of tremendous help for us to understand how to handle those aspects moving forward.<\/p>\n Ah, I finally get to write about my favorite feature of the release: automatic token lifecycle.<\/p>\n Besides the protocol and security details, one of the main pain points of working with authentication in rich clients is having to handle sessions. Obtaining a token is only the start: if you want to access the protected resource more than once, you need to save the token somewhere; retrieve it when you need it again, possibly after the app has been closed and reopened; verify that it is still valid; if you have more than one resource, ensure that you are retrieving the right token; and so on. You normally have to worry about all that, while at the same time minimizing the times in which you prompt the user for credentials without adding any security horrors in the process. OAuth2 provides a super-useful artifact for handling that, the refresh token, however that comes at the cost of extra moving parts in the session management logic.<\/p>\n What if I\u2019d tell you that AAL for Windows Store takes care of all that for you, without requiring any explicit action? By default, AAL for Windows Store engages with a persistent token cache every single time you invoke AcquireTokenAsync. The cache entry structure is shown below:<\/p>\n Further below you can find a flowchart describing exactly what happens, but for the ones among you preferring text to visuals:<\/p>\n Say that you invoke AcquireTokenAsync passing myresource, myclientid, and myloginhint (the other parameters are not used in the cache). <\/li>\n<\/ol>\n<\/li>\n<\/ol>\n Flowchart:<\/p>\n The bottom line is: use AcquireTokenAsync<\/span> every time you need a token<\/span><\/em><\/strong>. AAL will take care of querying the cache for you and even transparently refresh when necessary. The user will be prompted only when there\u2019s absolutely no other alternative.<\/p>\n In this release the default cache implementation is very simple: everything is handled transparently, the only explicit operation you can do is flushing its content via the Clean()<\/strong> method. The next refresh will offer a more sophisticated cache, offering fine grained access to the entries. Windows 8 and Windows RT have a great feature, the Password Vault<\/a>, which is what allowed us to easily set up a persistent token cache.<\/p>\n The idea is pretty simple: every Windows Store app have one secure store that can be used for saving credentials, accessed via the PasswordVault class. Can you believe it? A per-app isolated area, which survives across multiple launches of the app, right out of the box! That was just the perfect fit for a persistent token cache. AAL uses the PasswordVault as a flat store for the cache entries of the form described earlier: there is no direct connection to a particular\u00a0 AuthenticationContext instance, given that every entry is keyed per authority there\u2019s really no need for it; every cache operation goes straight to the Vault app-wide.<\/p>\n As added bonus, the use of the PasswordVault grants to AAL\u2019s cache a very interesting capability: cross-devices roaming of the saved tokens<\/strong>. In short: say that you install App1 on one of your Windows 8 or Windows RT devices and you authenticate using it. Say that you pick up another device of yours, and you install App1 there as well. At first launch of App1 you might discover that you are already authenticated without the need of entering any credentials!<\/p>\n I can\u2019t say that we did this intentionally, that was not a feature high in the stack, but it just comes with the use of the Vault. In fact, there\u2019s really nothing we can do to influence it from code: the way in which roaming takes place is more of a function of how your user\u2019s machines are configured. The rules determining how roaming takes place are summarized in the picture above. If you refer to those rules there should be no surprise roams: if you don\u2019t want roam to happens you can enforce your choices via devices settings or by opting out from the default caching implementation altogether.<\/p>\n All in all, pretty awesome In closing of this long deep dive, I want to mention few things that are not strictly inherent to AAL itself, but are aspects of working with Windows Azure AD and rich clients you have to be aware of.<\/p>\n If you\u2019ve been using AAL .NET for authenticating against services, or in fact wrote any<\/em> rich client accessing protected remote resources in the last 10 years or so, you are already familiar with the authentication model: there is an authority that knows about the service you want to invoke, and that knows how to authenticate you; if you can prove who you are, you get a token that grants you access to the service. In that picture, it does not really matter which rich client you are using: if you write code that implements that flow in a WPF app you can copy & paste it as is in any other WPF app, WinForm app, Excel plugin, Visual Studio extension and whatever else comes to mind without having to change anything on the authority and service side.<\/p>\n Well, the above holds for classic authentication protocols; but it does not (usually) hold anymore when you use an authorization framework like OAuth2, which happens to be what is used by AAL for Windows Store to drive the authentication flow.<\/p>\n
\nToday we are announcing the next batch of preview features for Windows Azure Active Directory. You can find most details in Alex\u2019 announcement here<\/strong><\/a>, but in a nutshell:<\/p>\n\n
<\/p>\nAAL in a Nutshell<\/h2>\n
\n
\n
<\/p>\n
\nGiven the nature of Windows Store apps, for which server to server authentication flows would not make much sense, AAL for Windows Store focuses exclusively on enabling user-based, interactive authentication<\/em>. Behind the scenes, AAL for Windows Store implements that flow using the new OAuth2 code grant endpoints in Windows Azure AD.<\/p>\nScenario and Programming Model<\/h2>\n
).<\/p>\n\n
\n(e.g. REST or otherwise, which parameters\/verbs\/etc to use,\u2026)<\/li>\n<\/a><\/p>\n\n
\n
3:<\/span> HttpClient httpClient = new<\/span> HttpClient();<\/pre>\n\n
\n
<\/p>\nMore About the Object Model<\/h3>\n
AuthenticationContext<\/h4>\n
Construction<\/h5>\n
\nThis is largely a function of the protocol types supported by the WebAuthenticationBroker, and the availability of such protocols on the service side. AAL for Windows Store engages with Windows Azure AD via the new code grant endpoints, but those endpoints are not available for ACS namespaces.<\/p>\nMethod AcquireTokenAsync<\/h5>\n
IAsyncOperation<AuthenticationResult> AcquireTokenAsync(string<\/span> resource, string<\/span> clientId);<\/pre>\n. As you guys send us feedback, we\u2019ll have more data on how you use AcquireTokenAsync and on if we need to add more overloads.<\/p>\nProperty TokenCache<\/h5>\n
Method AcquireTokenbyRefreshTokenAsync<\/h5>\n
AuthenticationResult<\/h4>\n
Property AuthenticationStatus Status<\/h5>\n
Property string AccessToken<\/h5>\n
Property DateTime ExpiresOn<\/h5>\n
Property string RefreshToken<\/h5>\n
Properties string Error, string ErrorDescription<\/h5>\n
Windows Store Exclusive Features<\/h2>\n
AAL for Windows Store is a Windows Runtime Component<\/h3>\n
<\/a><\/p>\n
\nAAL for Windows Store it is packaged as a Windows Runtime Component<\/span><\/strong>, a file with extension .winmd.<\/p>\n<\/p>\nWebAuthenticationBroker and App Capabilities<\/h3>\n
) is very handy: it\u2019s basically a system dialog, with fixed rules for size, positioning and consistent look & feel, which providers are standardizing on. It also takes specific steps for maintaining a level of isolation between the app itself and the context in which the authentication takes place.<\/p>\n
\nIn practice, the WAB has useful features that can be used even when wrapped hence it\u2019s worth calling it out. The main one, I\u2019d say, is the way in which it handles cookies.<\/p>\nAAL and WAB\u2019s Cookie Management<\/h4>\n
<\/a><\/p>\nWindows Store Application Capabilities<\/h4>\n
<\/a><\/p>\n\n
Token Lifecycle: Persistent Cache, Automatic Refresh, Roaming<\/h3>\n
<\/p>\n<\/a><\/p>\n
\nAAL looks up in the cache if there is an entry matching the Windows Azure AD tenant associated to the current AuthenticationContext, myresource and myclientid, myloginhint.<\/p>\n\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
<\/a><\/p>\n
\nAAL uses the default cache implementation using the ITokenCache interface methods, which means that you can plug in your own cache implementation if you so choose. In this phase, however, I would rather\u00a0 have you guys tell us which features you\u2019d like in the default cache, so that we can incorporate them and give you the best experience right out of the box.<\/p>\nAAL for Windows Store Cache and Windows\u2019 Password Vault<\/h4>\n
<\/a><\/p>\n
\nWithin the Windows Runtime execution environment, data saved in that area can only be accessed by the app that wrote them, when operated by the user that was logged in Windows at save time<\/em><\/strong>.<\/p>\n
\nIn summary:<\/p>\n\n
\n
<\/p>\nClient Registration and Permissions Settings<\/h2>\n