{"id":2664,"date":"2014-02-16T17:43:13","date_gmt":"2014-02-17T00:43:13","guid":{"rendered":"http:\/\/www.cloudidentity.com\/blog\/?p=2664"},"modified":"2014-02-16T17:47:24","modified_gmt":"2014-02-17T00:47:24","slug":"adal-net-servicing-release-and-the-never-flag","status":"publish","type":"post","link":"https:\/\/www.cloudidentity.com\/blog\/2014\/02\/16\/adal-net-servicing-release-and-the-never-flag\/","title":{"rendered":"ADAL .NET Servicing Release and the Never Flag"},"content":{"rendered":"

The team just published an update to ADAL .NET<\/a>: you can find the new package in ADAL\u2019s home on NuGet here as v1.0.3<\/a>.<\/p>\n

This is largely a service update – most of the work that went on it is bug fixing: we adjusted some weird cache behavior, we improved ADAL\u2019s behavior in error-prone situations such as temporary lack of connectivity, and so on.<\/p>\n

We did add one new feature, though. We extended the PromptBehavior<\/font> enum to include a new value, Never<\/font><\/strong>. Let\u2019s dig into that for a bit.<\/p>\n

You might recall from earlier posts<\/a> that ADAL\u2019s AcquireToken<\/font> has an overload accepting a parameter of type PromptBehavior<\/font>. Until v1.0.2, PromptBehavior<\/font> featured the following two values:<\/p>\n

  • Auto<\/font><\/strong>: the default. In this mode, ADAL will do everything in its power to return a token complying to the requirements passed in the AcquireToken<\/font> call (issued for that specific clientID, scoped for the requested resource, etc) without showing a UI: that boils down to looking up the cache for a corresponding cached token, failing that looking up for a suitable (MRRT<\/a>) refresh token and using it. If that fails to retrieve a token, ADAL falls back to popping out a dialog hosting a browser and navigating to the authorization endpoint of the authority of choice (Windows Azure AD, ADFS).
    This is the typical behavior you want when you trust the library to minimize user prompts but you can tolerate such prompts to pop out when needed.
    \n
  • Always<\/font><\/strong>: this flag tells ADAL to disregard the cache and refresh token lookups, and directly prompt the user regardless of the cached state.
    You\u2019ll want to do this when you want to guarantee that the user is given an opportunity of specifying a different account from the ones that might already have been used to obtain the tokens already present in cache. Say that you are developing an application which shows side by side resources from different tenants: you want to be able to obtain tokens for multiple, different users and keep them all in the cache at once. Say that you already got a token for resource R with user A: without something like the Always flag, a 2nd call to AcquireToken<\/font> for R would always automatically pick up the token you obtained with A, preventing the user from ever being able to specify B.\n

    Those two values are fine and dandy, but in fact they don\u2019t cover all possible behaviors you might want to get from AcquireToken<\/font>. Say that you are doing some background work, like refreshing a secondary view, and that work requires you to access protected resources. Your user is focused on the primary view and does not even know that you are doing work on the background. Say that the token acquisition for some of the resources you are accessing in the background fails to take place via cache: would you interfere with the main view and interrupt the user\u2019s work with a credential prompt out of the blue? The user would not even understand why he\/she is being prompted!<\/p>\n

    That is why we are introducing a new value in PromptBehavior<\/font>:<\/p>\n

  • Never<\/font><\/strong>: this flag guarantees that no UI will be displayed in the context of the present AcquireToken<\/font> call.
    It tells ADAL to do whatever it is in its power to obtain the requested token without showing any UI, just like for Auto<\/font>, but if that fails it should stop and return an error that you can trap and handle as you deem appropriate for your application. For example, just to give you an idea: if the resource you were trying to access has a visual representation in your UI you could add a little warning icon or any other signal which gently informs the user about the current state and provide an affordance to explicitly initiate an interactive authentication flow when he\/she sees fit.\n

    If the story would stop here, I\u2019d say it would be already interesting: but it gets better \"Smile\" to explain how, I have to peel off an abstraction layer and tell you a bit about the inner workings of the authentication flows and the .NET platform.<\/p>\n

    When you go through a successful interactive AcquireToken<\/font> flow, the state of your app is altered in two aspects:<\/p>\n

  • ADAL\u2019s token cache gets a new entry: access token, refresh token, occasionally user info, and so on. if you are working with Windows Azure AD, the refresh token is actually a TGT-like artifact<\/a> which will allow you to silently obtain other access tokens for other resources within the same tenant<\/em>.\n
  • As the interaction entails popping out a browser and authenticating to one or more web sites (the IdPs that serve pages for authenticating you: Windows Azure AD, MSA if you are using a guest account, etc) the web flow results in one or more session cookies that are now saved in your process\u2019 cookie jar, where they will stay as long as your process is up or you explicitly nuke them (via some DLL imports).\n

    Now comes the good part. The effect of the Never<\/font> flag is not to suppress all browser activity in case the cache & refresh token lookup fails: rather, it is to use an invisible browser to hit the authorization endpoint<\/em>. Aha, I can almost see a light in your eyes! \"Smile\" This has two implications:<\/p>\n

  • If you already have a session cookie in my process jar for the IdP you want, for example thanks to a preceding interaction, the Never flag will allow you to get a token with no UI interaction even if you don\u2019t have any suitable refresh tokens in the cache\n
  • For guest scenarios, like the ones in which you use an MSA for accessing Windows Azure management APIs, use of Never<\/font> +<\/em> the presence of an MSA cookie allows you to silently obtain tokens cross-tenant <\/em>\u2013 whereas MRRTs are bounded to work within a single tenant.\n

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

    Phase 1: get a token via usual interactive flow<\/em><\/p>\n

    Phase 2: delete the token cache content for any reason<\/em><\/p>\n

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

    Phase 3: profit! Ehmm, I mean \u2013 using the Never<\/font> flag the cookie from the process jar is picked up and used to authenticate silently<\/em><\/font><\/p>\n

     <\/p>\n

  • \n

    That is pretty neat! But it is also very abstract. How about a quick demonstration of #1? Consider the following code.<\/p>\n

    \n
       1:  <\/span>AuthenticationContext ac = <\/pre>\n
       2:  <\/span>     new<\/span> AuthenticationContext(\"https:\/\/login.windows.net\/contoso7.onmicrosoft.com\"<\/span>);<\/pre>\n
       3:  <\/span> <\/pre>\n
       4:  <\/span>\/\/the first call shows the UI<\/span><\/pre>\n
       5:  <\/span>AuthenticationResult ar = ac.AcquireToken(\"https:\/\/contoso7.onmicrosoft.com\/RichAPI\"<\/span>,<\/pre>\n
       6:  <\/span>                    \"be182811-9d0b-45b2-9ffa-52ede2a12230\"<\/span>,<\/pre>\n
       7:  <\/span>                    new<\/span> Uri(\"http:\/\/whatevah\"<\/span>));<\/pre>\n
       8:  <\/span> <\/pre>\n
       9:  <\/span>\/\/the 2nd call hits the cache<\/span><\/pre>\n
      10:  <\/span>ar = ac.AcquireToken(\"https:\/\/contoso7.onmicrosoft.com\/RichAPI\"<\/span>,<\/pre>\n
      11:  <\/span>                    \"be182811-9d0b-45b2-9ffa-52ede2a12230\"<\/span>,<\/pre>\n
      12:  <\/span>                    new<\/span> Uri(\"http:\/\/whatevah\"<\/span>));<\/pre>\n
      13:  <\/span> <\/pre>\n
      14:  <\/span>\/\/flush the cache<\/span><\/pre>\n
      15:  <\/span>ac.TokenCacheStore.Clear();<\/pre>\n
      16:  <\/span> <\/pre>\n
      17:  <\/span>\/\/the cookie jar already has the right cookie - the browser briefly flashes in and out of view<\/span><\/pre>\n
      18:  <\/span>ar = ac.AcquireToken(\"https:\/\/contoso7.onmicrosoft.com\/RichAPI\"<\/span>,<\/pre>\n
      19:  <\/span>                     \"be182811-9d0b-45b2-9ffa-52ede2a12230\"<\/span>,<\/pre>\n
      20:  <\/span>                     new<\/span> Uri(\"http:\/\/whatevah\"<\/span>));<\/pre>\n
      21:  <\/span>\/\/flush the cache again<\/span><\/pre>\n
      22:  <\/span>ac.TokenCacheStore.Clear();<\/pre>\n
      23:  <\/span> <\/pre>\n
      24:  <\/span>\/\/this call is like the 3rd call, but the Never flag makes it fully silent<\/span><\/pre>\n
      25:  <\/span>ar = ac.AcquireToken(\"https:\/\/contoso7.onmicrosoft.com\/RichAPI\"<\/span>,<\/pre>\n
      26:  <\/span>                    \"be182811-9d0b-45b2-9ffa-52ede2a12230\"<\/span>,<\/pre>\n
      27:  <\/span>                    new<\/span> Uri(\"http:\/\/whatevah\"<\/span>),<\/pre>\n
      28:  <\/span>                    PromptBehavior.Never);<\/pre>\n<\/div>\n