image

I have been longing to publish this post for a looong time Smile
Today we are announcing the next batch of preview features for Windows Azure Active Directory. You can find most details in Alex’ announcement here, but in a nutshell:

  • We now have endpoints capable of handling the OAuth2 code grant flow
  • We are releasing a preview of the Windows Azure Authentication Library for Windows Store – it’s available directly from VS as a NuGet package

As much as I am excited about the endpoints, it’s 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’s finally time to let it fly.

This walkthrough and this sample 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’s easy!

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! Smile

This is not required reading, come along for the ride only if you are very curious about it.

AAL in a Nutshell

If you are new to AAL, you might want to take a look at the intro post here: but in brief, the Windows Azure Authentication Library (AAL) makes it very easy for developers to add to their client applications the logic for authenticating users to Windows Azure Active Directory, and obtain access tokens for securing API calls.  No deep protocol expertise required!

Here there’s the laundry list of the main features in AAL for Windows Store:

  • Easy programming model for adding Windows Azure AD authentication to Windows Store apps
    • Take advantage of your Office365 accounts to authenticate in your Windows Store apps, too!
  • Works with Windows 8 and Windows RT devices
  • Support for multi factors authentication
  • Can be used from both C# and JavaScript/HTML5 apps
  • Persistent token cache
  • Automatic, just-in-time token refresh
  • Token roaming across trusted devices
  • easy-to-use wrap of the WebAuthenticationBroker API for business apps

I am definitely biased, but that sounds pretty exciting to me… Smile

AAL for Windows Store is not our first foray in the client authentication space. We already have a preview of AAL 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.
Given 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. Behind the scenes, AAL for Windows Store implements that flow using the new OAuth2 code grant endpoints in Windows Azure AD.

Scenario and Programming Model

As mentioned, AAL for Windows Store tries to solve about the same class of problems tackled by AAL .NET. Here there’s a short excerpt from the original announcement, describing the basic scenario from the PoV of the developer (that would be you! Smile).

  • I know I want to call service A, and I know how to call it
    (e.g. REST or otherwise, which parameters/verbs/etc to use,…)
  • Without knowing other details, I know that to call A I need to present a “token” representing the user of my app
  • I know that Windows Azure AD knows all the details of how to do authentication in this scenario, though I might be a bit blurry about what those details might be

image

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:

  1. Initialize an instance of the AuthenticationContext class, which represents the Windows Azure AD tenant that knows about the users and the services/resources you want to work with
  2. Ask to your AuthenticationContext instance to to get a token for your client to access your target service, by invoking it method AcquireTokenAsync passing client and target service info
    1. the library takes care of all the necessary authentication experience (though often it won’t be required, see the token lifecycle section)
  3. AcquireTokenAsync returns an AuthenticationResult instance. If the operation was successful, you can extract the token from its AccessToken property and use it to call your target service

For once, I am not oversimplifying: that is exactly what happens. Here there’s some C# code implementing the sequence, in the case in which the target resource is a REST service:

1: AuthenticationContext authenticationContext =

new AuthenticationContext(“https://login.windows.net/treyresearch1.onmicrosoft.com”);

2: AuthenticationResult result =

await authenticationContext.AcquireTokenAsync(“http://myapps/quotesapp,

“2b8606b7-6bad-4e8b-ac3c-1356aca8ab0e”);

   3: HttpClient httpClient = new HttpClient();

4: httpClient.DefaultRequestHeaders.Authorization =

new AuthenticationHeaderValue(“Bearer”, result.AccessToken);

5: HttpResponseMessageresponse =

await httpClient.GetAsync(https://poorsmanas.azurewebsites.net/api/InspiringQuotes);

 

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’s see what happens in a bit more detail, line by line.

  1. This line creates an instance of AuthenticationContext tied to the Windows Azure AD tenant TreyResearch1.
  2. Here we ask to our AuthenticationContext to get for us a token to access the service identified by the URI “http://myapps/quotesapp”. In order to do so, the corresponding Windows Azure AD tenant must know the client app originating the request, hence we provide the ID identifying the app as well (more details later). Here two things can happen:
    1. the call returns right away, in case a suitable token is already available in the cache (more details in the section about caching)
    2. the call triggers the display of the WinRT’s WebAuthenticationBroker dialog, presenting the user with the Windows Azure AD authentication experience.

      Assuming that the authentication took place successfully

  3. We create a new HttpClient
  4. We add an HTTP Authorization header, containing the token obtained in #2 and formatted according to the OAuth2 bearer resource access style
  5. We invoke the service; the presence of the token in the header provides the access info that the resource needs to verify before granting access.

…and that’s all you need to do! Smile

More About the Object Model

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’ll have a complete MSDN reference, but for the time being here there’s a quick glance at the main primitives.

AuthenticationContext

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’s some more details on how it works.

Construction

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’s URL. There is an overload of the constructor which allows you to turn validation off, should you need to do so for development purposes.

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.
This 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.

Method AcquireTokenAsync

You already encountered the simplest form of AcquireTokenAsync:

IAsyncOperation<AuthenticationResult> AcquireTokenAsync(string resource, string clientId);

 

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.

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>. You’ll read more about this in the section on Windows Store features; here I’ll just say that the use of such URI will cause the WebAuthenticationBroker used during authentication to operate in “SSO mode”.

AcquireTokenAsync has another overload, taking far more parameters:

IAsyncOperation<AuthenticationResult> AcquireTokenAsync(string resource, string clientId,

string redirectUri, string loginHint, string extraQueryParameters);

 

The first two parameters are the same as the ones in the first overload.

redirectUri 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’s SSO mode for this call ; and so on.

loginHint allows you to specify the username (e.g. adam@treyresearch1.onmicrosoft.com) 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.

extraQueryParameters is there for giving you more latitude. The Windows Azure AD authorization server might accept more parameters in the future, and we don’t 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.

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… but I lost that battle Smile. As you guys send us feedback, we’ll have more data on how you use AcquireTokenAsync and on if we need to add more overloads.

Property TokenCache

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.

If you need to customize the caching logic, you can write your own cache (implementing the ITokenCache 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.

If you want to get rid of caching altogether, all you need to do is assigning TokenCache to null.

Method AcquireTokenbyRefreshTokenAsync

IAsyncOperation<AuthenticationResult> AcquireTokenByRefreshTokenAsync(

string refreshToken, string clientId);

If for some reason you don’t want to (or can’t) take advantage of the automatic refresh of tokens offered by the AAL cache, you have the opportunity of getting matters in your own hands. The method AcquireTokenbyRefreshTokenAsync (yep, we plan to improve the name: any ideas?) allows you to pass a refresh token (usually obtained from a former call to AcquireTokenAsync) and a client ID to trigger a token refresh.

AuthenticationResult

All token acquisition operations result in an AuthenticationResult 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.

Here there’s the full list of public members:

Property AuthenticationStatus Status

Communicates the outcome of the authentication operation. Possible values, from the enum AuthenticationStatus, are Succeeded and Failed.

Property string AccessToken

Upon successful authentication (or positive cache hit) this property holds the bits of the token intended to be used for the target resource.

Property DateTime ExpiresOn

This value indicates the time at which the token will expire.

Property string RefreshToken

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.

Properties string Error, string ErrorDescription

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.

Windows Store Exclusive Features

The Windows Runtime API, coupled with the Windows Store apps “sandboxing” system, offers an extremely powerful platform to build on. Here there’s a list of the areas in which AAL takes advantage of Windows Runtime specific features to help you handling authentication as smoothly as possible.

AAL for Windows Store is a Windows Runtime Component

image

There are many languages you can choose from when it comes to developing Windows Store applications: C#, JavaScript/HTML5, C++… we wanted to make sure you retain that freedom when you use AAL.

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 come as an assembly/DLL: that would constrain its usage to Windows Store apps written in C# and VB.
AAL for Windows Store it is packaged as a Windows Runtime Component, a file with extension .winmd.

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’s pretty sweet! Smile

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!

WebAuthenticationBroker and App Capabilities

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 class.

The WebAuthenticationBroker (can I call it WAB from now on? it’s really long to type Smile) is very handy: it’s 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.

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’d have to construct the exact URL containing the request for the authorization endpoint; and once you’d get back the code, you’d be responsible to parte the request to retrieve it and use it to hit the token endpoint with the right message format.

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)  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.
In practice, the WAB has useful features that can be used even when wrapped hence it’s worth calling it out. The main one, I’d say, is the way in which it handles cookies.

AAL and WAB’s Cookie Management

Authentication cookies management in Windows Store is less straightforward than on the classic desktop, and that influences how AAL for Windows Store operates.

image

When you use AcquireTokenAsync without specifying a return URL, AAL invokes the WAB in “SSO mode”. 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.

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 “low trust” 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.

That’s 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().

Windows Store Application Capabilities

image

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.

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

  • Ability to navigate to intranet locations
  • Ability to leverage domain authentication for the current user
  • Ability to access certificate stores and smartcards for multifactor authentication

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’s really impossible for us to know in advance what will be required (that’s 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’d know at a given time, the authenticating authority can change policy much faster than your app’s install/update lifecycle.

For those reasons, if you don’t 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.

Token Lifecycle: Persistent Cache, Automatic Refresh, Roaming

Ah, I finally get to write about my favorite feature of the release: automatic token lifecycle.

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.

What if I’d tell you that AAL for Windows Store takes care of all that for you, without requiring any explicit action? Smile

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:

image

Further below you can find a flowchart describing exactly what happens, but for the ones among you preferring text to visuals:

Say that you invoke AcquireTokenAsync passing myresource, myclientid, and myloginhint (the other parameters are not used in the cache).
AAL 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.

  1. if there is an entry
    1. is there a valid access token?
      1. if there is, return the cache entry right away
      2. if there isn’t
        1. is there a refresh token?
          1. if there is, use it
            1. if the refresh succeeded, replace the old entry and return it
            2. if the refresh did not succeed, prompt the user for auth
              1. if successful, save results in cache and return
              2. if unsuccessful, return error info
          2. if there isn’t, prompt the user for auth
              1. if successful, save results in cache and return
              2. if unsuccessful, return error info
  2. if there isn’t, prompt the user for auth
    1. if successful, save results in cache and return
    2. if unsuccessful, return error info

Flowchart:

image

The bottom line is: use AcquireTokenAsync every time you need a token. AAL will take care of querying the cache for you and even transparently refresh when necessary. The user will be prompted only when there’s absolutely no other alternative.

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() method. The next refresh will offer a more sophisticated cache, offering fine grained access to the entries.
AAL 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  have you guys tell us which features you’d like in the default cache, so that we can incorporate them and give you the best experience right out of the box.

AAL for Windows Store Cache and Windows’ Password Vault

Windows 8 and Windows RT have a great feature, the Password Vault, which is what allowed us to easily set up a persistent token cache.

image

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.
Within 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.

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  AuthenticationContext instance, given that every entry is keyed per authority there’s really no need for it; every cache operation goes straight to the Vault app-wide.

As added bonus, the use of the PasswordVault grants to AAL’s cache a very interesting capability: cross-devices roaming of the saved tokens. 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!

I can’t 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’s 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’s machines are configured. The rules determining how roaming takes place are summarized in the picture above.
In summary:

  • outgoing roaming only happens if the user is signed in the machine with a Microsoft Account AND the machine is listed as a trusted device in the corresponding Microsoft Account settings.
    • However if the machine is also domain joined, outgoing roaming does NOT take place.
  • inbound roaming happens on devices where the same originating app is installed, the receiving device is marked as trusted by the same Microsoft Account, and the Microsoft Account (or a domain account linked to that Microsoft Account) is present on the device

If you refer to those rules there should be no surprise roams: if you don’t want roam to happens you can enforce your choices via devices settings or by opting out from the default caching implementation altogether.

All in all, pretty awesome Smile

Client Registration and Permissions Settings

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.

If you’ve been using AAL .NET for authenticating against services, or in fact wrote any 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.

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.

I won’t repeat here the mega-post I wrote on the relationship between OAuth2 and sign on, nor I will start a dissertation about whether accessing a protected resource from a rich client amounts to “sign in”; those will come in some future post. Here I’ll just list some practicalities about how things are different and what to do about it to make AAL for Windows Store work in your apps.

The idea here is that you are not as much authenticating the user; rather, you are authorizing the app to access the resource on behalf of the user. The idea might sound subtle, but once again it has important consequences.

App Registration

The first consequence is that now the identity of the client application does matter. No longer just a transparent extension of the user, the app in itself is an active actor whose identity has an impact on whether access will be granted or denied: the exact same user might gain access to a resource when using App1, but see his/here requests denied when using App2. As such,  your client apps need to be registered in your Windows Azure AD tenant.

As counterintuitive as it might sound, the entity used for representing your client is a ServicePrincipal Smile or in fact an Application object (see here for more details).

Here there’s a dump of the Application object representing one of my test clients:

{
     "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Application",
     "objectType": "Application",
     "objectId": "d22366d4-2692-4074-a079-0eabad5dbaa3",
     "appId": "2b8606b7-6bad-4e8b-ac3c-1356aca8ab0e",
     "availableToOtherTenants": false,
     "displayName": "Todo Client",
     "errorUrl": null,
     "homepage": null,
     "identifierUris": [
       "ms-app://s-1-15-2-4261528085-3522513112-2976465067-1243652757-3393620086-3686240607-3579810098/"
     ],
     "keyCredentials": [],
     "mainLogo@odata.mediaContentType": "image",
     "logoutUrl": null,
     "passwordCredentials": [],
     "publicClient": true,
     "replyUrls": [
       "ms-app://s-1-15-2-4261528085-3522513112-2976465067-1243652757-3393620086-3686240607-3579810098/"
     ],
     "samlMetadataUrl": null
   }

 

The schema is the same, but it is used a bit differently: without going too much in details, note the appId (which in AAL for Windows Store is used as clientid in AcquireTokenAsync) and the reply URL, which happens to be one of the SSO ones that the WAB likes.

The corresponding ServicePrincipal (from now on SP) is not terribly interesting, but I’ll paste it anyway in case you are curious:

{
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ServicePrincipal",
      "objectType": "ServicePrincipal",
      "objectId": "47ed0cac-fb08-4f3c-844f-96fecefdc165",
      "accountEnabled": true,
      "appId": "2b8606b7-6bad-4e8b-ac3c-1356aca8ab0e",
      "displayName": "Todo Client",
      "errorUrl": null,
      "homepage": null,
      "keyCredentials": [],
      "logoutUrl": null,
      "passwordCredentials": [],
      "publisherName": "Microsoft AAA",
      "replyUrls": [
        "ms-app://s-1-15-2-4261528085-3522513112-2976465067-1243652757-3393620086-3686240607-3579810098/"
      ],
      "samlMetadataUrl": null,
      "servicePrincipalNames": [
        "ms-app://s-1-15-2-4261528085-3522513112-2976465067-1243652757-3393620086-3686240607-3579810098/",
        "2b8606b7-6bad-4e8b-ac3c-1356aca8ab0e"
      ],
      "tags": []
    }

 

…all pretty standard.

Permissions

As of today, registering the client is necessary but not sufficient condition for your app to access a service. You need to let your Windows Azure AD tenant know that your app has the necessary permissions to access the service(s) you are targeting.

That can be achieved by adding a suitable entry in yet another new entity, the Permissions collection. Such entry must tie the SP’s entry of your client with the SP entry of the target service, and declare the access level the client should enjoy. Here there’s the entry enabling the client described above:

{
      "clientId": "47ed0cac-fb08-4f3c-844f-96fecefdc165",
      "consentType": "AllPrincipals",
      "expiryTime": "9999-12-31T23:59:59.9999999",
      "objectId": "rAztRwj7PE-ET5b-zv3BZcw8dYEmKBdGl7heaQ_BLzU",
      "principalId": null,
      "resourceId": "81753ccc-2826-4617-97b8-5e690fc12f35",
      "scope": "user_impersonation",
      "startTime": "0001-01-01T00:00:00"
 }

 

Now, don’t get confused! The clientId here is not the clientid you’d use in AAL for Windows Store for identifying the client (that would be the SP’s appId). Rather, it is the objectId of the SP representing the client; you can verify by comparing with the earlier entries.
The resourceId, I am sure you already guessed it, is the objectId of the SP representing the service.

The other interesting value there is scope: the ones among you familiar with OAuth2 will recognize it. In short, that’s simply the kind of access the client has to the service: in this case, accessing it as the user (which for interactive rich apps is pretty much the equivalent of the more traditional user authentication flows).

With that entry, Windows Azure AD has all it needs for enabling the scenario. All you need to do is plugging the correct values in the AAL for Windows Store API, hit F5 and watch the magic unfold.

The Graph Explorer

image

Although you can – if you so choose – create the entries for the client app and the permission element directly via the Graph API, you don’t have to.

The Graph Explorer has been updated to help you do both tasks with just few clicks: the walkthrough and the sample guide you though the exact procedure you need to follow.

Note: the entries for your clients will appear in the Windows Azure portal, alongside the ones of the Web apps you are creating following the GA path. For now the portal does not expose the necessary settings: I’ll ask what the official guidance is, but for the time being my recommendation (you do remember my disclaimer, right?) would be to avoid modifying those entries via web UI.

2FA!

image

A short note here to highlight that the same tricks for supporting multi factor authentication shown in this post for AAL .NET will work for AAL for Windows Store, too: just authenticate as a user who was marked for 2Fa, and watch your Windows Store app gain an extra level of authentication assurance without changing a line of code Smile

Next

Well, I promised a long post, and a long post you got.

I know that the ability of using Windows Azure AD from Windows Store apps was one of the most requested features in the past few months, and I can’t tell you how impatient I am to see how you will use this preview Smile

You can expect the next update to AAL .NET to incorporate some of the innovations we have in AAL for Windows Store, like the use of AuthenticationResult as a return type and the support for the OAuth2 code grant flow. How much of the rest makes its way back in the library, and how AAL for Windows Store, will in large part depend on your feedback. Happy coding Winking smile

 

4 Responses to Windows Azure Authentication Library (AAL) for Windows Store: a Deep Dive

  1. Windows Azure Authentication Library (AAL) for Windows Store: a Deep Dive…

    Thank you for submitting this cool story – Trackback from Wazurr Community…

  2. [...] For more details on AAL for Windows Store, please refer to this deep dive post. [...]

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>