Nick's .NET Travels

Continually looking for the yellow brick road so I can catch me a wizard....

Visual State Transitions in Xamarin Forms with Animations

In previous posts (Visual States in Xamarin.Forms using BuildIt.Forms and Xamarin.Forms Visual States with View Models) I demonstrated how the BuildIt.Forms library (https://www.nuget.org/packages/BuildIt.Forms) could be used to declare visual states for pages, and controls, within Xamarin Forms. Today we just added some basic support for animations so that as you transition between visual states you can animate elements of the screen:

The following visual states define animations for rotating a green square:

<Grid HeightRequest="100" WidthRequest="100" x:Name="AnimateGrid" HorizontalOptions="Start" BackgroundColor="Green" />

The Hide visual state defines three animations that run in parallel, with the rotation being a sequence of animations. The Show visual state has the reverse animations to return the green square to the original starting position. Unlike the setters, there’s no built in support for returning the element to its unchanged state.

<vsm:VisualStateManager.VisualStateGroups>
     <x:Array Type="{x:Type vsm:VisualStateGroup}">
         <vsm:VisualStateGroup Name="SampleStates">
             <vsm:VisualState Name="Show">
                 <vsm:VisualState.Animations>
                     <vsm:TranslateAnimation TranslationX="0" Duration="500" Target="AnimateGrid"/>
                     <vsm:FadeAnimation Opacity="1" Duration="500" Target="AnimateGrid"/>
                     <vsm:RotateAnimation Rotation="0" Duration="500" Target="AnimateGrid"/>
                 </vsm:VisualState.Animations>
             </vsm:VisualState>
             <vsm:VisualState Name="Hide">
                 <vsm:VisualState.Setters>
                     <vsm:Setter Value="false"
                                 Target="WelcomeText.IsVisible" />
                 </vsm:VisualState.Setters>
                 <vsm:VisualState.Animations>
                     <vsm:ParallelAnimation>
                         <vsm:TranslateAnimation TranslationX="200" Duration="3000" Target="AnimateGrid"/>
                         <vsm:FadeAnimation Opacity="0.2" Duration="3000" Target="AnimateGrid"/>
                         <vsm:SequenceAnimation>
                             <vsm:RotateAnimation Rotation="135" Duration="750" Target="AnimateGrid"/>
                             <vsm:RotateAnimation Rotation="0" Duration="750" Target="AnimateGrid"/>
                             <vsm:RotateAnimation Rotation="135" Duration="750" Target="AnimateGrid"/>
                             <vsm:RotateAnimation Rotation="0" Duration="750" Target="AnimateGrid"/>
                         </vsm:SequenceAnimation>
                     </vsm:ParallelAnimation>
                 </vsm:VisualState.Animations>
             </vsm:VisualState>
         </vsm:VisualStateGroup>
     </x:Array>
</vsm:VisualStateManager.VisualStateGroups>

This is how these animations play out:

animations

Adding Fluent Design Acrylic Material to UWP via Xamarin.Forms.

At Build Microsoft made a big deal out of the new Fluent Design that they’re encouraging developers to start taking advantage of. Out of the box it’s a little harder to take advantage of these features but using BuildIt.Forms it’s easy to start using acrylic material resources. Let’s extend the example I’ve covered in the last couple of posts (Visual States in Xamarin.Forms using BuildIt.Forms and Xamarin.Forms Visual States with View Models). I’ve added a Grid, that will span the whole page (the StackLayout was positioned to keep all the elements in the centre of the page) and included the BackgroundEffect to set the background of the whole page.

<Grid>
     <Grid.Effects>
         <ctrls:BackgroundEffect Resource="SystemControlAcrylicWindowBrush" />
     </Grid.Effects>

     <StackLayout VerticalOptions="Center"
                     HorizontalOptions="Center">

        <Label x:Name="WelcomeText"
                 Text="{Binding WelcomeText}" />
         <StackLayout Orientation="Horizontal">
             <Button Text="Show"
                     Clicked="ShowClicked" />
             <Button Text="Hide"
                     Clicked="HideClicked" />
         </StackLayout>
     </StackLayout>
</Grid>

The Resource attribute defines the UWP brush resource that will be used as the background. In this case the SystemControlAcrylicWindowBrush is one of the build in arcylic brushes. As you can see the page appears as translucent, allowing what’s behind the app to taint the background of the app.

image

It’s also possible to use a custom acrylic resource, defined in the App.xaml of the UWP application

<Application
     x:Class="FormsWithStates.UWP.App"
     xmlns="
http://schemas.microsoft.com/winfx/2006/xaml/presentation"
     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
     xmlns:local="using:FormsWithStates.UWP"
     RequestedTheme="Light">
     <Application.Resources>
         <ResourceDictionary>
             <ResourceDictionary.ThemeDictionaries>
                 <ResourceDictionary x:Key="Default">
                    <AcrylicBrush x:Key="MyAcrylicBrush"
                                   BackgroundSource="HostBackdrop"
                                   TintColor="#FFFF0000"
                                   TintOpacity="0.4"
                                   FallbackColor="#FF7F0000" />

                 </ResourceDictionary>

                <ResourceDictionary x:Key="HighContrast">
                     <SolidColorBrush x:Key="MyAcrylicBrush"
                                      Color="{ThemeResource SystemColorWindowColor}" />

                 </ResourceDictionary>

                <ResourceDictionary x:Key="Light">
                     <AcrylicBrush x:Key="MyAcrylicBrush"
                                   BackgroundSource="HostBackdrop"
                                   TintColor="#FFFF0000"
                                   TintOpacity="0.4"
                                   FallbackColor="#FFFF7F7F" />

                 </ResourceDictionary>
             </ResourceDictionary.ThemeDictionaries>
         </ResourceDictionary>
     </Application.Resources>
</Application>

image

The BackgroundEffect also supports a FallbackColor attribute which can be used to set the background colour on all platforms.

Xamarin.Forms Visual States with View Models

In my previous post, Visual States in Xamarin.Forms using BuildIt.Forms, I showed how to use BuildIt.Forms (https://www.nuget.org/packages/BuildIt.Forms) to create visual states that can be used to define how the user interface changes to reflect different states of the page. The example demonstrated switching between visual states in the code behind with calls to VisualStateManager.GoToState. In this post I’m going to extend the example to allow the states to be switched from a view model.

I’ll start by creating a view model that will be data bound to the page. Usually I’d use a framework like MvvmCross to drive the view model/view instantiation but for this example I’ll keep it simple. I will however still put the view model in a separate project – again this promotes good separation between the view models and their associated view. I’ll create a new .NET Standard library, FormsWithStates.Core, and add a reference to it into the FormsWithStates.UI project.

image

I’ll add a new class to the project, MainViewModel, which will be the view model for the MainPage of the application. To track states within the view model, I need to add a reference to the BuildIt.States library on NuGet.

image

The MainViewModel will define a simple property WelcomeText to demonstrate that the view model is indeed data bound to the page. It also implements the interface IHasStates which defines a property StateManager – you can think of the IStateManager implementation as an object that can track states and state transitions.

public enum SampleStates
{
     Base,
     Show,
     Hide
}

public class MainViewModel : IHasStates
{
     public IStateManager StateManager { get; } = new StateManager();

    public string WelcomeText => "Welcome to Forms!";

    public MainViewModel()
     {
         StateManager.Group<SampleStates>().DefineAllStates();
     }

    public void Show()
     {
         StateManager.GoToState(SampleStates.Show);
     }
     public void Hide()
     {
         StateManager.GoToState(SampleStates.Hide);
     }
}

The enumeration SampleStates defines the states that the MainViewModel references – both the enumeration and the states themselves have to match the names of the visual state group and visual states defined in the XAML for the page. The final step is to link the visual states on the page to the IStateManager instance, so that when there is a state change in the IStateManager, it will be reflected on the page via a change to the visual states. This is done by the Bind method on the VisualStateManager class.

public partial class MainPage : ContentPage
{
     private MainViewModel ViewModel { get; } = new MainViewModel();
     public MainPage()
     {
         InitializeComponent();

        BindingContext = ViewModel;
         VisualStateManager.Bind(this, ViewModel.StateManager);
     }

    public void ShowClicked(object sender, EventArgs e)
     {
         ViewModel.Show();
     }
     public void HideClicked(object sender, EventArgs e)
     {
         ViewModel.Hide();
     }
}

Whilst from the perspective of a user, there is no difference (since the Show and Hide buttons do the same thing), state management has been shifted to the view model where it can be tested. This separation of views and view models is important to ensure all application logic can be tested.

Visual States in Xamarin.Forms using BuildIt.Forms

A couple of weeks ago I started building out some helpers to make working with Xamarin.Forms a little nicer (see Styling Pages and Controls in Xamarin Forms using Visual States,Rebuilding the Xamarin.Forms Button with Visual States and Control Templates and Ambient Properties in Xamarin.Forms). Since then we’ve been working on building out a library that encapsulates these features, again making it easier for us and others to build apps using Xamarin.Forms. There is now a pre-release version of BuildIt.Forms (https://www.nuget.org/packages/BuildIt.Forms) that anyone can reference to take advantage of these helpers. The library makes use of some methods/properties that are only available in the pre-release version of Xamarin.Forms, which is why we don’t have an actual release out yet.

In this post I’m going to walk through using visual states in a Xamarin.Forms project. To set the scene, I’m going to step through creating a new Xamarin.Forms project in Visual Studio 2017 (current RTM build, not the preview, although the preview build should be similar). I’ll do this in this post to make sure the basics of creating a Xamarin.Forms project that uses a .NET Standard Library instead of a PCL library is covered. I highly recommend switching to a .NET Standard library as soon as possible to avoid issues with upgrading nuget references etc (most third party library now have a .NET Standard version and it will become increasingly harder to maintain and update your old PCL libraries).

Ok, so let’s get started with a new project – I’m going with the Cross Platform App (Xamarin) template in the New Projects dialog:

image

Next, I’ll select the Blank App template, using Xamarin.Forms (UI Technology) and Portable Class Library (Code Sharing Strategy). Side note here – I highly recommend not using the Shared Project option for Code Sharing Strategy; using this option is a recipe for disaster as it promote poorly separated UI logic and allows for using conditional compilation based on #defines which is not a good strategy if you want maintainable code.

image

After clicking OK my solution has four projects: A PCL which has got the Xamarin.Forms UI defined in XAML files, and three “head” projects, one for each target platform. At this point, I would suggest running each project to make sure you have a working application before going any further (and commit this code to your source repository before going any further!)

image

Now to replace the PCL with a .NET Standard library. I’ll add a new .NET Standard class library. I like to make it clear that this library will contain the UI for my Xamarin.Forms project by using the .UI suffix. I do not include my view models in this library – I’ll talk about this in a subsequent post.

image

After creating the new class library, I just need to copy across the XAML and .cs files that were in the PCL library (App.xaml, App.xaml.cs, MainPage.xaml, MainPage.xaml.cs).  I can then remove the PCL library from the solution. Of course, I need to go through each of the head projects and add a reference to the UI project.

image

At this point I would again build and run the application on each platform – If you do this without doing anything the solution won’t compile as the UI library doesn’t have a reference to the Xamarin.Forms NuGet library. I suggest adding a reference to the Xamarin.Forms NuGet library and then upgrading any libraries where there is an update available. Again before proceeding, build and run each platform.

The next step is to add a reference to BuildIt.Forms. This is a prerelease library so you’ll need to check the “Include prerelease” option when searching. You need to add this library to all projects, even though you’ll only be adding code into the UI project – this makes sure the platform specific libraries that are included in BuildIt.Forms are correctly referenced and will be included.

image

As part of referencing BuildIt.Forms you will notice that the reference to Xamarin.Forms has also been updated to the prerelease version – as BuildIt.Forms takes advantage of some prerelease APIs this is unavoidable at the moment. The official release of BuildIt.Forms will not be available until the next drop of Xamarin.Forms where these APIs come out of prerelease.

Now we can start to make use of some of the helpers in BuildIt.Forms. In this case we’re going to use visual states in the XAML for the MainPage to hide and show a Label. The following XAML includes a Label and two Button elements. There are two visual states defined: Show and Hide (the actual names are only relevant when switching visual states, they have no bearing on what the visual states do). Note that the Show visual state doesn’t need to explicitly set the IsVisible property on the WelcomeText Label to true, since this is the default value for that property.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="
http://xamarin.com/schemas/2014/forms"
              xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
              xmlns:vsm="clr-namespace:BuildIt.Forms.Core;assembly=BuildIt.Forms.Core"
              xmlns:local="clr-namespace:FormsWithStates"
              x:Class="FormsWithStates.MainPage">
     <vsm:VisualStateManager.VisualStateGroups>
         <x:Array Type="{x:Type vsm:VisualStateGroup}">
             <vsm:VisualStateGroup Name="SampleStates">
                <vsm:VisualState Name="Show" />
                 <vsm:VisualState Name="Hide">
                     <vsm:VisualState.Setters>
                         <vsm:Setter Value="false"
                                     Target="WelcomeText.IsVisible" />
                     </vsm:VisualState.Setters>
                 </vsm:VisualState>

             </vsm:VisualStateGroup>
         </x:Array>
     </vsm:VisualStateManager.VisualStateGroups>
     <StackLayout VerticalOptions="Center"
                  HorizontalOptions="Center">
         <Label x:Name="WelcomeText"
                Text="Welcome to Xamarin Forms!" />
         <StackLayout Orientation="Horizontal">
             <Button Text="Show"
                     Clicked="ShowClicked" />
             <Button Text="Hide"
                     Clicked="HideClicked" />
         </StackLayout>
     </StackLayout>
</ContentPage>

The code for the event handlers for the two button is relatively simple:

public void ShowClicked(object sender, EventArgs e)
{
     VisualStateManager.GoToState(this, "Show");
}
public void HideClicked(object sender, EventArgs e)
{
     VisualStateManager.GoToState(this, "Hide");

}

And the final result is an interface that shows and hides the welcome text on the page:

imageimage

Feel free to try out the BuildIt.Forms library and get started using visual states within your Xamarin.Forms project.

Ambient Properties in Xamarin.Forms

One of the aspects of XAML that is often misunderstood is that of ambient properties. Probably the best example of this is being able to set the foreground colour on a Page in UWP and for the foreground color to be set on every element on the page. Unfortunately this doesn’t seem to be something that’s available in Xamarin.Forms, which lead me to wonder how hard it would be to implement.

The implementation would be slightly different from UWP which uses the AmbientAttribute. Instead I’ll create an attached property which can be set on any element. The ForeColor will be then set on each child element, unless the TextColor is explcitly set on an element.

For example the following XAML

<StackLayout
    vsm:Ambient.ForeColor="Blue">
     <Label Text="Hello World - Blue!" />
     <Label TextColor="Red"
             Text="Hello World - Red!" />
</StackLayout>

would generate the following output

image

Over the next couple of days the Ambient.ForeColor property will be added to BuildIt.Forms, which also includes the VisualStateManager I described in my past two posts (here and here).

Rebuilding the Xamarin.Forms Button with Visual States and Control Templates

In my previous post I provided a demonstrable way that visual states could be used in a Xamarin.Forms application to adjust layout. Whilst I showed how this can be used on a page to show/hide a piece of text, it can also be used to define the different states of a button. Before I get onto using visual states within a button, I’ll first show how a ContentView can be adapted to provide the basic button behaviour, whilst allowing both Content and ControlTemplate to be defined. Ok, perhaps that doesn’t make sense but let’s walk through an example:

<controls:ContentButton Pressed="ToggleButtonPressed">
    <StackLayout>
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
    </StackLayout>
</controls:ContentButton>

In this code, I can add any XAML elements as Content within the ContentButton tags. The ContentButton raises a Pressed event, instead of a Click or Clicked event, to which an event handler can be attached. In the next code snippet, I’ve overridden the default ControlTemplate, wrapping the ContentPresenter in a Grid which has a yellow background.

<controls:ContentButton VerticalOptions="Center"
                        x:Name="DisabledButton"
                        HorizontalOptions="Center">
    <ContentView.ControlTemplate>
        <ControlTemplate>
            <Grid BackgroundColor="Yellow">
                <ContentPresenter x:Name="ContentPresenter"
                                    Content="{TemplateBinding Content}" />
            </Grid>
        </ControlTemplate>
    </ContentView.ControlTemplate>
    <StackLayout>
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
    </StackLayout>
</controls:ContentButton>

Overriding the ControlTemplate demonstrates an easy way to override the style of the button in a way that can be replicated across all instances of the button in an application.

Let’s take a look at the inner workings of the ContentButton, in particular the default ContentTemplate which is used to define different visual states of the button. In this case there are four visual states: Normal, PointerOver, Pressed and Disabled.

<ContentView.ControlTemplate>
    <ControlTemplate>
        <Grid x:Name="RootGrid" BackgroundColor="{TemplateBinding BackgroundColor}">
            <local:VisualStateManager.VisualStateGroups>
                <x:Array Type="{x:Type local:VisualStateGroup}">
                    <local:VisualStateGroup Name="CommonStates">
                        <local:VisualState Name="Normal" />
                        <local:VisualState Name="PointerOver">
                            <local:VisualState.Setters>
                                <local:Setter Value="#33000000" Target="Background.BackgroundColor" />
                            </local:VisualState.Setters>
                        </local:VisualState>
                        <local:VisualState Name="Pressed">
                            <local:VisualState.Setters>
                                <local:Setter Value="#66000000" Target="RootGrid.BackgroundColor" />
                            </local:VisualState.Setters>
                        </local:VisualState>
                        <local:VisualState Name="Disabled">
                            <local:VisualState.Setters>
                                <local:Setter Value="#33000000" Target="Background.BackgroundColor" />
                            </local:VisualState.Setters>
                        </local:VisualState>
                    </local:VisualStateGroup>
                </x:Array>
            </local:VisualStateManager.VisualStateGroups>
           
<BoxView BackgroundColor="Transparent" x:Name="Background" />
            <ContentPresenter x:Name="ContentPresenter" Content="{TemplateBinding Content}" />
        </Grid>
    </ControlTemplate>
</ContentView.ControlTemplate>

In this code you can see how the visual states (which I introduced in my previous post) are used to adjust the background colour of the BoxView that sits behind the Content of the button.

The sample project that demonstrates the ContentButton can be downloaded here

Styling Pages and Controls in Xamarin Forms using Visual States

I’ve been a bit proponent of both Xamarin and Xamarin.Forms for a long time but recently I’ve been taking another look at some of the fundamentals. Xamarin.Forms, for all its great intent is still a poor-man’s answer to declaring layout of an application in Xaml. Unlike Xaml platforms that have come before it (WPF, Silverlight, UWP), Forms doesn’t support some of even the basic features that you’d expect. On the chopping board today is the Button control – as one of the fundamental controls for any application, the Button should be able to be completely customised. Unfortunately it’s far from easy to alter the look of the basic button.

If you look at how a simple button renders on different platforms, there is a clear difference between the style of the button. The following image shows how the button control renders across UWP, iOS and Android (UWP has an extra visual state as it supports mouse/pointer over on desktop).

image

Button States Across Three Platforms

The difference in style is by design – the rendering of the button on each platform uses the built in style for each platform. This works well if you’re interesting in building a generic looking application (eg perhaps a simple LOB data capture application). However, if you want to style the button in line with your branding and the design of your application, you’re going to want to make the buttons look and behave the same across all devices. You’d think this would be as simple as defining a common style, or perhaps overriding the default layout of the button. This is in fact doable – for example on UWP you can use an implicit style to override the look of every button across the application.

Having to override the style of the button on each platform defeats the purpose of using Forms in the first place – once you’ve overridden the style, you then need to make platform specific changes every time you want to alter the style of the button control; imagine doing this for every control in your application – pretty soon, you might as well have developed the application using the traditional Xamarin model, rather than Forms. So, let’s look at the limitations of the Button control and see what we can do to address some of its shortcomings in a way that will help us build better applications quicker.

There are two issues that I have with the Button control. The first is that it’s not easy to customise the content within the Button itself. For example if you wanted to have two lines of text, with the first being centred in bold, and the second justified italics with word wrapping enabled to allow it to flow to multiple lines. In UWP this would be easy with the Button control as the Content could be customised to have multiple TextBlock elements, with the style set accordingly.

<Button>
    <StackPanel>
        <TextBlock Text="Hello World!"
                    TextAlignment="Center"
                    FontWeight="Bold" />
        <TextBlock Text="This is a short message that should word wrap with all the lines being set to justified"
                    FontStyle="Italic"
                    TextWrapping="WrapWholeWords"
                    TextAlignment="Justify" />
    </StackPanel>
</Button>

This would look similar to the following:

image

UWP Button with Custom Content

Attempting to do this with the Forms Button control is not trivial. The second issue is how the different visual states are handled. Again in UWP the different Button visual states are defined in XAML (generic.xaml) where appropriate properties are set based on the active states (eg Normal, Pressed, PointerOver). Forms doesn’t support Visual States, so attempting to define Button states declaratively is going to take more work.

My solution to these issues comes in two steps: firstly, provide a declarative way to define Visual States in XAML, similar to what’s available in UWP; and secondly to provide an alternative to the Button which can not only take custom content but also has a template that can be override to customise behaviour for different button states. If you’ve ever drilled into a control template for a UWP control, chances are that it has some visual states defined. Rather than having some predefined behaviour that’s not accessible or customisable, the various states of UWP controls are defined in XAML in the template for the control. In addition to defining the different states within a control, visual states can be used to define different states of a page too.

In this post we’ll focus on the first step, which is how to define in XAML and then apply visual states. Visual states are defined in visual state groups, and only a single state within a given states group can be active at any time (ie they’re mutually exclusive). However, it is possible that two states, from different groups can be active at any point in time.

So far we know we need visual states, defined within visual state groups. Within each visual state we need to be able to define which properties are going to change when the visual state is made active. UWP allows the property changes to be defined either as a storyboard, potentially with animation, or as a series of setters where the property is updated to the new value immediately. For the purposes of getting the basics working, we’re just going to work with property setters.

Let’s work with a very simple scenario where we have a simple Label which we need to be able to show and hide based on the state of the page:

<Label FontSize="30"
        x:Name="HelloLabel"
        Text="Hello World!" />

In our very contrived example we have a button that will be used to toggle whether the Label is visible.

private bool visible = true;
public void ToggleButtonPressed(object sender, EventArgs e)
{
    visible = !visible;
    VisualStateManager.GoToState(this, visible ? "Show":"Hide");
}

This code, by design, is similar to what you might see within a UWP application that uses visual states to control the layout – in this case showing and hiding an element. Currently visual states don’t exist in Xamarin Forms but here’s a first pass on an implementation of visual states:

<vsm:VisualStateManager.VisualStateGroups>
    <x:Array Type="{x:Type vsm:VisualStateGroup}">
        <vsm:VisualStateGroup Name="LabelStates">
            <vsm:VisualState Name="Show" />
            <vsm:VisualState Name="Hide">
                <vsm:VisualState.Setters>
                    <vsm:Setter Value="false"
                                Target="HelloLabel.IsVisible" />
                </vsm:VisualState.Setters>
            </vsm:VisualState>
        </vsm:VisualStateGroup>
    </x:Array>
</vsm:VisualStateManager.VisualStateGroups>

For those familiar with the syntax in UWP this should look familiar – there’s a few kinks to work out (for example the use of the Array tag) but in its initial form it works.

Sample project can be downloaded here

Thinking about Synchronisation in a Cloud-First World

As a mobile applications enthusiast from way back before Windows Mobile was a thing (yeh, I mean the first time), one of the challenges has always been data synchronisation. The challenge comes down to a trade off between stale data and user experience. Simple applications don’t worry about any form of data synchronisation; instead relying on pulling whatever data they need, when they need it. Unfortunately, these applications feel like the user is always waiting on data, or worse, seeing no data or error messages when there’s no connection. In order to fix, what is essentially a user experience issue, application developers often look at caching, or synchronising, data so that it can be made available offline. This both improves performance, since data is read from what’s cached on the device, it also means the data can be access when offline. The inevitable question is then how much data should be cached, and how should data be synchronised.

There is no golden-bullet when it comes to identifying what data needs to be cached on the device. Some applications only cache data that the user has chosen to look at; allowing them to come back and review the data at a later point without having to request the data again. Other applications will proactively cache all data related to the current user – whilst this seems like a good idea initially, as the data related to a user increases, so does the time taken to complete an initial, or even future, synchronisations. In addition, the logic to retrieve all data related to a user can grow in complexity, often resulting in more data than necessary being retrieved, to ensure no data is omitted.

Data synchronisation used to be an important topic with several attempts being made by Microsoft to assist developers. For example there was a Windows Mobile client for Merge Replication; there was the Microsoft Sync Framework and more recently the Mobile App Service has a limited form of data synchronization. Unfortunately none of these methods are well supported. Nor are they optimised to take advantage of some the benefits of the cloud.

Let’s look at the most recent attempt by Microsoft to provide a synchronisation framework for mobile apps – Offline Data Sync for Azure Mobile Apps. The basic premise is that the application defines a table, or a query on a table, that will be pulled into a local Sqlite database. Local changes can be made to the data. Data can then be synchronised by pulling any server side changes and pushing local changes to the server. The architecture has the mobile application connecting to a service, which then either retrieves data from the database, or submits changes to the database.

Thinking about how a cloud application should scale, there are a number of issues with this architecture:

  • If you look at how to scale cloud applications, having any services which connect directly to the database, can be a source for bottlenecks. I’m definitely not advocating for no relational database, just a bit of separation between the service tier and the database, such that most service calls don’t block waiting for the database to be available.
  • Connecting directly to services is a very slow way to retrieve data – it involves querying the database, processing the data into the format to be returned, and then returning it directly from the service instance. Compare this to retrieving the same data, pre-fetched and available via a CDN. The latter is going to be significantly faster, will cut down on bandwidth costs, will reduce load on both services and database since they no longer have to do work for every request for data.
  • Changes submitted to the services have to be applied directly to the database – if the database is offline, or otherwise unavailable, the service call will fail. Even if the data can be written immediately, there is a latency involved which increases the execution time of the service. This means more scaling of the service and slower responses back to the mobile application.

Reading between the lines you might notice that there are two areas that I want to investigate to see if there’s an opportunity to improve data synchronisation for cloud applications:

  1. Data retrieval: If we take the stance that the services won’t retrieve data directly from the database and return it to the mobile application, we need to think about how we can pre-fetch data and publish it out so it can be retrieved via the CDN. Of course, we don’t want to be publishing out the entire dataset into a single file which updates every time there is a change to the database, as this would undo any benefits of using the CDN. CDNs are optimised for immutable data; if you go trying to make changes to a file that’s already been published, you’ll run into a bunch of issues around caching of the data both in the CDN and on the client. Additionally, you don’t want the mobile application to download the entire dataset every time it needs to update. I’ll come back to talk more about the structure of the data but for the moment the assumption is that data will be retrieved and saved into an immutable file that will be placed in blob storage, making it accessible via the CDN.
  2. Data changes: Changes to data are a little harder as the initial standpoint for any developer is that changes should be immediately sent to the database, otherwise the database will be out of date. One of the realisations learnt by a lot of social sites (as they represent some of the largest datasets available) is that they rely on Eventual Consistency. In some data synchronisation cases, eventual consistency isn’t an option but for the other scenarios, it’s important to consider the use of queues to break up the change workflow. For example when a mobile app sends a change to the service, the service can simply queue the change and respond back a successful acknowledgement. When the change gets popped off the queue and the change applied to the database, a new message can go on the queue to indicate the response. When this message is popped off the queue, a notification is sent back to the mobile application indicating that the data has been saved to the database.

It’s been a while since I’ve reviewed synchronisation logic but it’s become evident that there are some interesting options that are now possible with the Azure cloud platform. I want to visit both of these areas in much more detail.

Screenshots for a UWP Xbox App

We’ve been doing a bit of work building out an Xbox app and part of the fit-and-finish of any app is aligning the application layout with those of the designs. One of the easiest ways to do this is to take a screenshot of the app and then mark it up alongside the original designs, which are hopefully high enough fidelity to allow you to do the final round of tweaks against. On Xbox we noticed that within a UWP application the normal double-tap of the Xbox button doesn’t seem to take a screenshot. This is was confirmed by a post on the forum (https://social.msdn.microsoft.com/Forums/en-US/e100560d-a26b-48f8-a2bf-acce75ea4d26/uwpxbox-how-to-capture-screenshot-on-xbox-one-for-uwp-app?forum=wpdevelop) where the recommendation was to write code to take a screenshot.

I even started down the path of using similar code to extract a screenshot, when I remembered there was a developer portal that’s exposed when you switch the device into dev mode (see https://docs.microsoft.com/en-us/windows/uwp/xbox-apps/devkit-activation). I figured that once I took a screenshot using code, I’d need a way to get the image off the console, and that the developer portal was the way to do this.

The first thing to do is to go to Dev Home – there should be a link on the right of the home screen when your console is in developer mode. If you don’t see it but you’ve setup dev mode, it may be that your device has reverted to retail mode, in which case you’ll need to run the dev mode activation app again.

image

In Dev Home, there is an option to “Manage Xbox Device Portal”

image

Where you have one option, “Enable the Device Portal”

image

Once enabled you’ll need to configure authorisation by specifying username and password – write these down as you’ll need them shortly to access the dev portal.

image

The next step is to go to a computer that’s on the same network as the Xbox (or at least a network that can reach the Xbox). Enter the IP address with the corresponding port number (see previous screenshot which is shown after enabling device portal, which shows the IP address and port number of your console).

image

In most browser (this was Edge, but similar behaviour happens on most modern browsers) you’ll see a warning that the site you’re attempting to access can’t be verified. You need to expand, in this case, Details in order to see a link that will allow you to continue on to the device portal.

image

Now that you’re in the device portal, select the Media capture node on the left.

image

Click the “Capture Screenshot” at any point to screenshot whatever’s currently being displayed on the Xbox.

image

You’ll also be prompted to open or save the captured image.

Why String Interpolation is a BAD thing

So I’ll set the scene – I was reviewing some code and refactoring it. First thing to do was to go through and take a look at the Resharper comments as they do a good job at tightening up sloppy code. In this instance I came across code that looked a bit like this:

var url = “http://someservice.com/”;
url += queryParameters;
DoSomething(url);

Of course, this can easily be refactored using string interpolation to

var url = $“http://someservice.com/{queryParameters}”;
DoSomething(url);

Which looks so much cleaner. Unfortunately this has actually just made my code even worse – I still have this horrible nasty string literal, now with embedded code. Argh, who does this stuff. Next step, factor the string out into a constants, or ideally configuration file.

private const string ServiceUrlTemplate = “http://someservice.com/{0}”;

and then:

var url = string.Format(Constants.ServiceUrlTemplate,queryParameters);
DoSomething(url);

I’m sure there are a ton of other ways to make this nicer and perhaps more readable but having a string literal with interpolation is not one of them.

Additional Note: If you’re not using Resharper or another equivalent tool, you’re not working effectively. Start using a refactoring tool today and don’t ignore the warnings. Spend time everyday reviewing and improving the code you write

Call out to the ADAL team! – Authenticate Using External Browser

In my post, Authorizing Access to Resources using Azure Active Directory, I talk about authenticating using the built in browser on the device, rather than authenticating via a webview, which is all too common. Unfortunately despite being fully supported by Azure Active Directory, the team responsible for ADAL haven’t, as far as I can tell, provided support for using an external browser to authenticate.

I was super impressed when I just downloaded the Facebook app on Windows, that it supports “Log in with Browser”.

image

In my opinion, this not only represents a more secure form of authentication (since I can validate the website I’m signing into), it is also a better experience, since I’m already logged into Facebook in the browser anyhow.

I definitely encourage developers to consider using the external browser, rather than supporting SDKs and libraries that us the in-app browser.

Unable to Connect or Debug to Visual Studio Android Emulator with Visual Studio 2017 RC

Now I do appreciate that running prerelease software comes with some risk and I’m also aware that emulators are hard to get working 100% right on every machine. Ever since I can remember there have been connectivity issues with Windows Mobile, Windows Phone and now Windows 10 Mobile emulators; whether connectivity meaning to the internet, the local machine or being able to debug an application. So, it came as no surprise that after rebuilding my computer and installing Visual Studio 2017 RC that my installation of the Visual Studio Android Emulator was semi-broken. Turns out I had two issues I needed to overcome.

When I attempted to launch the emulator, I got the following notice, saying that the Internet Connection needs to be configured – this is pretty typical for first run as Hyper-V needs to setup the virtual switches that the emulator image will use.

image

After clicking Yes, the emulator is launched and my application is deployed. Unfortunately when Visual Studio attempts to launch the application and attach the debugger, the application closes immediately. This is again an issues I’ve seen before and in fact it appears on the troubleshooting web page for the Android Emulator (https://msdn.microsoft.com/en-us/library/mt228282.aspx):

- After you’ve run the emulator image the first time, close the Android Emulator

- Open Hyper-V Manager

- Select the virtual machine that matches the emulator you were attempting to run (make sure it’s in the Off state), and click Settings

- Under Processor –> Compatibility –> check the “Migrate to a physical computer with a different processor version” checkbox

image

- Click OK

- Important: Make sure you stop and restart the Hyper-V service, otherwise, for some reason the setting is lost the next time you run the emulator.

Having done this I can now deploy and run applications on the emulator. The next issue was that for some reason the emulator couldn’t access the internet. I took a look in the Virtual Switch Manager in Hyper-V Manager (click Virtual Switch Manager from the Actions list on the right side of the Hyper-V Manager management console) and there was only a single “Windows Phone Emulator Internal” switch.

image

I clicked on New virtual network switch, selected External Access and gave the switch a name:

image

Each emulator virtual machine needs to have access to both the internal and external switches, so after clicking OK to exit the Virtual Switch Manager, I clicked on the virtual machine that I want to assign the new virtual switch to. Make sure you’ve stopped the virtual machine (closing the Android emulator will do this). Click Settings, click Add Hardware and select Network Adapter and click Add.image

From the Virtual switch dropdown, select the virtual switch you just created (External Access in my case), and click OK.

image

Now launch the emulator (either via the Visual Studio Android Emulator interface that can be launched from the Start menu independently of Visual Studio, or by attempting to run an application from Visual Studio) and you should now have internet access – check via the web browser in the emulator if you’re in any doubt.

UseWindowsAzureActiveDirectoryBearerAuthentication v’s UseJwtBearerAuthentication for Authorization with Azure Active Directory for an ASP.NET Web API

In my previous post, Securing a Web API using Azure Active Directory and OWIN, I covered how to authorize requests against Azure Active Directory using the UseWindowsAzureActiveDirectoryBearerAuthentication extension method in the OWN startup class. This extension method has been designed specifically for Azure Active Directory but if you think about it, the Authorization token is just a JWT token, so in theory you could take a much more generic approach to authorizing access by validating the JWT. This can be done using the UseJwtBearerAuthentication extension method.

There are a couple of steps to using the UseJwtBearerAuthentication extension method. Firstly, in order to validate the signature of the JWT, we’re going to need the public certificate that matches the key identifier contained in the JWT. In my post on Verifying Azure Active Directory JWT Tokens I cover how to examine the JWT using https://jwt.io in order to retrieve the kid, retrieve the openid configuration, locate the jwks uri, retrieve the keys and save out the key as a certificate. In the post I used the certificate (ie wrapping the raw key in ---BEGIN---, ---END--- markers) to validate the JWT; in this case I’ve copied the contents into a text file which I’ve named azure.cer and added it to the root of my web project (making sure the build action is set to Content so it is deployed with the website).

The next thing to do is to remove the UseWindowsAzureActiveDirectoryBearerAuthentication extension method, replacing it with the following code.

var fileName = HostingEnvironment.MapPath("~/") + "azure.cer";
var cert = new X509Certificate2(fileName);
app.UseJwtBearerAuthentication(new JwtBearerAuthenticationOptions
{
    AllowedAudiences = new[] {ConfigurationManager.AppSettings["ida:Audience"]},
    IssuerSecurityTokenProviders = new IIssuerSecurityTokenProvider[]
    {
        new X509CertificateSecurityTokenProvider(ConfigurationManager.AppSettings["ida:IssuerName"], cert)
    }
});

This code uses the azure.cer certificate file combined with the Audience and IssuerName which I’ve added to the web.config.

<add key="ida:Audience" value="a07aa09e-21b9-4e86-b269-a18903b5fe54" />
<add key="ida:IssuerName" value="https://sts.windows.net/55cc17b5-7d2a-418e-86a6-277c54462485/" />

The Audience is the application id (aka client id) of the Azure application registration. The IssuerName needs to match to what appears in the JWT. Opening one of the tokens in https://jwt.io it’s the ISS value that you want to use as the IssuerName.
image

Now you can run the project and see that again the requests are validated to ensure they’re correctly signed.

Securing a Web API using Azure Active Directory and OWIN

In this post we’re going to look at how to use Azure Active Directory to secure a web api built using ASP.NET (full framework – we’ll come back to .NET Core in a future post). To get started I’m going to create a very vanilla web project using Visual Studio 2017. At this point VS2017 is still in RC and so you’ll get slightly different behaviour than what you’ll get using the Visual Studio 2015 templates. In actual fact the VS2015 templates seem to provide more in the way of out of the box support for OWIN. I ran into issues recently when I hadn’t realised what VS2015 was adding for me behind the scenes, so in this post I’ll endeavour not to assume anything or skip any steps along the way.

image

After creating the project, the first thing I always to is to run it and make sure the project has been correctly created from the template. In the case of a web application, I also take note of the startup url, in this case http://localhost:39063/. However, at this point I also realised that I should do the rest of this post following some semblance of best practice and do everything over SSL. Luckily, recent enhancements to IIS Express makes it simple to configure and support SSL with minimal fuss. In fact, all you need to do is select the web project node and press F4 (note, going to Properties in the shortcut menu brings up the main project properties pane, which is not what you’re after) to bring up the Properties window. At the bottom of the list of properties is the SSL Enabled and SSL URL, which is https://localhost:44331/. Take note of this url as we’ll need it in a minute.

image

To setup the Web API in order to authorize requests, I’m going to create a new application registration in Azure Active Directory. This time I need to select Web app / API from the Application Type dropdown. I’ll give it a Name (that will be shown in the Azure portal and when signing into use this resource) and I’ll enter the SSL address as the Sign-on URL. This URL will also be listed as one of the redirect URIs used during the sign in process. During debugging you can opt to do this over HTTP but I would discourage this as it’s no longer required.

image

After creating the application, take note of the Application Id of the newly created application. This is often referred to as the client id and will be used when authenticating a user for access to the web api.

Application Id (aka Client Id): a07aa09e-21b9-4e86-b269-a18903b5fe54

We’re done for the moment with Azure Active Directory, let’s turn to the web application we recently created. The authorization process for in-bound requests involves extracting the Authorization header and processing the bearer token to determine if the calling party should have access to the services. In order to do this for tokens issues by Azure AD I’ll add references to both the Microsoft.Own.Security.ActiveDirectory and Microsoft.Own.Host.SystemWeb packages.

image

Note: Adding these references takes a while! Make sure they’re completely finished before attempting to continue.

Depending on the project template, you may, or may not, already have a Startup.cs file in your project. If you don’t, add a new item based on the OWIN Startup class template

image

The code for this class should be kept relatively simple:

[assembly: OwinStartup(typeof(SampleWebApp.Startup))]
namespace SampleWebApp
{
    public partial class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            ConfigureAuth(app);
        }
    }
}

Additionally, you’ll want to add another partial class file Startup.Auth.cs in the App_Start folder.

namespace SampleWebApp
{
    public partial class Startup
    {
        public void ConfigureAuth(IAppBuilder app)
        {
        }
    }
}

And now we get to adding the middleware that will be used to process the authorization header

public void ConfigureAuth(IAppBuilder app)
{
    app.UseWindowsAzureActiveDirectoryBearerAuthentication(
        new WindowsAzureActiveDirectoryBearerAuthenticationOptions
        {
             Tenant = ConfigurationManager.AppSettings["ida:Tenant"],
             TokenValidationParameters = new System.IdentityModel.Tokens.TokenValidationParameters
             {
                 ValidAudience = ConfigurationManager.AppSettings["ida:Audience"]
             }
        });
}

This uses the configuration manager to extract the Tenant and Audience settings from the web.config (and subsequently the Azure portal settings when you publish to the cloud):

<add key="ida:Audience" value="a07aa09e-21b9-4e86-b269-a18903b5fe54" />
<add key="ida:Tenant" value="nicksdemodir.onmicrosoft.com" />

The tenant is the Id, or in this case, the domain of the tenant where the application is registered. The Audience is the application Id of the application registered in Azure AD.

Warning: If you run the application now and get an error relating to a missing type, you may have to revert the Microsoft.Owin.Security.ActiveDirectory to the most recent v4 package. At the time of writing this post there seems to be an incompatibility between v5 and Owin.

Reference to type 'TokenValidationParameters' claims it is defined in 'System.IdentityModel.Tokens.Jwt', but it could not be found

Ok, we’re ready to try making requests. I’m going to use Fiddler but you can use any other tool that’s able to generate and send HTTP requests. The first attempt will be a GET request to https://localhost:44331/api/values which is one of the default controllers that was created from the project template. Depending on what your project template included, the valuescontroller may, or may not, have the Authorize attribute applied to it. If, like me, you didn’t have the Authorize attribute applied to the valuecontroller, you should get a valid response back to your HTTP request. In this case, you’re going to want to add security to the valuecontroller by adding the Authorize attributes:

[Authorize]
public class ValuesController : ApiController
{

Now, try making the request again – you should now get a 401 Unauthorized error. The body of the response should say:

{"Message":"Authorization has been denied for this request."}

Clearly this is the case since we didn’t send the Authorization header. This time, let’s add an Authorization header, with the word “Bearer” and a token consisting of random text:

Authorization: Bearer abcdefg

This should generate the same response. However, let’s start to look into this further. To get more diagnostic information, add the following to the web.config file for the project

<system.diagnostics>
  <switches>
    <add name="Microsoft.Owin" value="Verbose" />
  </switches>
</system.diagnostics>

Now when you make the request you should see more diagnostic information in the Output window in Visual Studio:

Microsoft.Owin.Security.OAuth.OAuthBearerAuthenticationMiddleware Error: 0 : Authentication failed
System.ArgumentException: IDX10708: 'System.IdentityModel.Tokens.JwtSecurityTokenHandler' cannot read this string: 'abcdefg’.
The string needs to be in compact JSON format, which is of the form: '<Base64UrlEncodedHeader>.<Base64UrlEncodedPayload>.<OPTIONAL, Base64UrlEncodedSignature>'.

As we should have predicted, the token we passed in isn’t a value Jwt – it’s not even valid JSON. Let’s fix this by generating an actual access token for this Web API. In a previous post I walked through manually the process of authenticating, retrieving an authorization code and then exchanging it for an access token. I’ll do the same here.

First I’m going to launch an authorization url in the browser and sign in using credentials from the nicksdemodir.onmicrosoft.com tenant:

https://login.microsoftonline.com/nicksdemodir.onmicrosoft.com/oauth2/authorize?client_id=a07aa09e-21b9-4e86-b269-a18903b5fe54&response_type=code&redirect_uri=https://localhost:44331/

The authorization url is made up of various components:

nicksdemodir.onmicrosoft.com – This is the domain name of the tenant where the web application is registered with Azure AD. You can also use the tenant Id (guid format)

a07aa09e-21b9-4e86-b269-a18903b5fe54 – This is the application id of the application registration in Azure AD

code – This indicates that the response should be an authorization code

https://localhost:44331/  - This is the uri that the browser will be redirected back to, passing with it the code in the query string.

Make sure you have the web application running, otherwise the redirect uri won’t resolve at it may be hard to extract the code from the query string (depending on the browser). After signing in, you’ll be redirected back to your web application with a URL similar to (the code has been shortened for brevity):

https://localhost:44331/?code=zvrs_zz0…….05B_ggAA&session_state=ef2986b8-75bd-484a-b9b9-68f0e46ab569

The next thing to do is to prepare a POST request in your http tool of choice with the following:

URL: https://login.microsoftonline.com/nicksdemodir.onmicrosoft.com/oauth2/token

Body: grant_type=authorization_code&client_id=a07aa09e-21b9-4e86-b269-a18903b5fe54&client_secret=c06kP0Q9ENGpZGbiZTqB1QQaZUWNe190mCittRMr&redirect_uri=https://localhost:44331/&code=zvrs_zz0…….05B_ggAA&resource=a07aa09e-21b9-4e86-b269-a18903b5fe54

The Body parameters are broken down as:

a07aa09e-21b9-4e86-b269-a18903b5fe54 – This is the application id of the application registration in Azure AD. It’s required as both the client_id and the resource, since we’re using the access token to access the web application itself.

c06kP0Q9ENGpZGbiZTqB1QQaZUWNe190mCittRMr – This is a private key (aka client secret) issued by the Azure AD application to ensure the security of token requests. I’ll come back to this in a second and show how to create one for your application.

https://localhost:44331/ – The redirect uri for the application – required here to verify the calling party as it has to align with what’s in Azure AD

zvrs_zz0…….05B_ggAA – This is the authorization code returned in the previous step

To generate the client secret in Azure AD simply click on the Keys tab within the details of the application registration. You can then create a new key by entering a description. The description is only seen by you, so give it a name that’s meaningful to you. Note that once you save the new key, you will only be shown the value of the key once. Once you leave the page, the value of the key will never been shown again.

image

The key created in the Azure AD should be used as the client secret when doing the authorization code to access token exchange.

The response to this POST should return JSON which includes and access token value. Add the access token to the authorization header:

Authorization: Bearer G1ZsPGjPF6qJO8Sd5HctnKqNk_8KDc-………Lpy9P8sDWdECziihaPWyseug9hgD119keoZuh4B

This should give you a 200 response with data. And there you have it – you’ve successfully secured your web api so that it requires the user to be authenticated using Azure Active Directory.

Improving the Azure Active Directory Sign-on Experience

I was talking to a customer the other day and had to log into the Azure portal. Normally when I launch the portal I’m already signed in and I’m not prompted but for whatever reason this time I was prompted to authenticate. Doing this in front of the customer lead to three interesting discussions:

- Use of two factor authentication to secure sign in
- Separate global administrator account for primary organisation tenant
- Company branding for Azure AD sign in

Firstly, the use of two factor authentication (TFA) is a must requirement for anyone who is using the Azure portal – if you are an administrator of your organisation, please make sure you enforce this requirement for anyone accessing your tenant/directory/subscription. This applies to staff, contractors, guests etc who might be using your Azure portal or the Office 365 portal. In fact, in this day in age, I would be enforcing two factor authentication for all employees – note that Outlook and Skype for Business are still stuck in the dark-ages and don’t access TFA sign in. For these you’ll need to generate an application password (go to https://myapps.microsoft.com, click on your profile image in top right corner and select “Profile”, click through to “Additional security verification,” click on the “app passwords” tab and then click “Create” to generate an app password.

Ok, next is the use of a separate global administrator account – this is in part tied to the previous point about using TFA. If you’re a global administrator of your tenant and you enable TFA, you won’t be able to generate app passwords. This is essentially forcing you down the path of best practice, which is to have a separate account which is the global administrator for your tenant. If other people in your organisation need administrative permissions, you can do this on a user or role basis within the Azure portal – our preference is to assign permissions to a resource group but there is enough fidelity within the portal to control access at the level you desire.

The other thing we’ve also enforced is that we do not host any Azure resources in our primary tenant (ie in our case builttoroam.com). Given the importance of Office365 based services we felt it important that we isolate off any resources we create in Azure to make sure they’re completely independent of our primary tenant. The only exception to this is if we are building internal LOB applications (ie only apps for Built to Roam use) – for these we include the app registrations within the builttoroam.com tenant so that we can restrict sign in and at the same time deliver a great sign in experience for our employees. For example we’re using Facebook Workplace (https://workplace.fb.com/) – we configured this within the builttoroam.com tenant in Azure AD to allow for a SSO experience.

Now, onto the point of this post – the last thing that came out of signing into the portal in front of the customer was that they were startled when we went to sign into the portal and our company branding appeared. To illustrate, when you first land on the portal sign in page you see:

image

After entering my email address, the sign in page changes to incorporate the Built to Roam branding

image

This not only improves the perception (for internal and external users), it also gives everyone a sense of confidence that they’re signing into a legitimate Built to Roam service.

In order to set this up, you need to navigate to the Active Directory node in the Azure portal and click on the Company branding. If you’re using Office 365 you should already have access to this tab. However, if you’re not, you may need to sign up for Active Directory Premium – you can get started using the Premium trial:

image

Once you’ve opened the Company branding tab (if you have just activated the trial, you may need to wait a few minutes and/or sign out and back in again in order for the Company branding tab to open) you can click on the link to “Configure company branding now”

image

There are a number of options and images that you can configure:

image

After saving the changes, if you attempt to sign in, you’ll notice the new images/colours etc appear. In this case, you can see that the welcome text at the bottom of the sign in page has been changed to what I entered in the company branding tab. Unfortunately because I didn’t set the sign in page image, the default is used, so you can’t see the red (#FF0000) background I set – you can see glimpses of it if you resize the page. This can be fixed by simply uploading a transparent image.

image

The ability to customise the sign in experience is just one way to improve the experience for you staff and customers.

The Danger of Admin Consent for Applications

In the last couple of posts I covered the use of admin consent to grant permissions for an application to access more than simply data related to the signed in user:

Admin Consent for Permissions in Azure Active Directory

Making your Azure Active Directory application Multi-tenanted

In my initial post talking about admin consent I added the “Read directory data” to the set of permissions that the application would request. This permission, along with a number of other permissions for the Windows Azure Active Directory resource, have a green tick in the “Requires Admin” column.

image

It’s all to easy for developers, when setting up the permissions for an application to not think through what enabling permissions for an application does. When you enable permissions for an application, by ticking the box alongside the permission in the Azure AD application configuration (see previous) image, you are essentially saying that the application will be able to perform those actions after the user has signed in and provided consent – this is true regardless of what role the user belongs to within the organisation (the application can perform the same actions whether a receptionist or the CEO of an organisation is signed in).

The division between permissions that require admin consent, versus those that do not, usually are based on whether the permission is for an action that only administrators should be able to do, versus those that any user should be able to do. For example in the case of Windows Azure Active Directory all users should be able to sign in and read their profile, read the basic profile of all users in the directory and access the directory as the signed-in user – all of these do not require admin consent as they are either actions that pertain to the signed in user, or they are actions that all users should be able to perform. The last permission does permits more access control as elements within the directory can be secured so users/roles/groups can access them; if the user is accessing the directory as themselves, they’ll only be able to access objects that they have permissions on.

When I checked the box alongside the “Read directory data” permission, I was essentially saying that all users (assuming a global administrator had performed the admin consent) would be able to read all data in their organisation’s directory (see https://msdn.microsoft.com/en-us/library/azure/ad/graph/howto/azure-ad-graph-api-permission-scopes):

image

In order words, once someone has signed into the application, the access token granted to the application can be used to retrieve all directory data – ummm that’s starting to sound pretty scary. No imagine if I granted “Read and write directory data” permissions to the application. Now the access token can read and write directory data. Put this into the context of hackers who use social engineering to access low level employees, you can imagine it wouldn’t be hard for them to access this application in order to access employee information.

The moral of this post is DO NOT enable REQUIRES ADMIN permissions to any native application (unless you’re 100% sure you know what the implications are) – it’s way to easy to intercept access tokens and act on behalf of the user.

Making your Azure Active Directory application Multi-tenanted

So far in my previous posts I’ve discussed signing into an application using Azure Active Directory (Azure AD) using a basic application registration in Azure AD. Last post we added some additional permissions that required administrator consent. However, up until now, only users in the same directory (aka tenant) that the application is registered in, can sign in. In the case of the sample application I’ve been working with, the application is registered to the nicksdemodir.onmicrosoft.com tenant, so only users belonging to that tenant can sign in eg [email protected]. If I attempt to sign in with an account from a different tenant, I run into a few issues, and depending on what type of account I sign in with, the error that is displayed varies.

I’ll start by signing in with a regular user account that belongs to a different tenant (in this case btro365dev.onmicrosoft.com). When I attempt to sign in with this account, everything seems to go well – I’m prompted to sign in; I successfully sign in; I’m returned to the application where the code is exchanged for an access token. However, when I attempt to use this access token I get a rather cryptic error about an “Unsupported token” eg:

{"odata.error":{"code":"Request_BadRequest","message":{"lang":"en","value":"Unsupported token. Unable to initialize the authorization context."},"requestId":"86481ea2-79bd-461b-93ad-4f649286617a","date":"2017-01-25T21:28:14"}}

This is actually less cryptic than it seems – essentially it’s saying that I’m attempting to present a token that the API can’t process. If you were to open the access token in https://jwt.io, you’d see that the token has been issued by the nicksdemodir.onmicrosoft.com tenant (actually you’d see the STS url that correlates to this tenant) for an account that doesn’t exist in that tenant (eg [email protected]). Whilst this is a legitimate access token, when you present it to the Graph API, it attempts to retrieve information about the user in the issuing tenant, which of course fails, since the user doesn’t exist there.

Ok, let’s see what happens if I attempt to launch the admin consent prompt. In this case, after I sign in (now using [email protected] which is a global administrator) I get a more useful error message saying “AADSTS50020: User account … does not exist in tenant”.

image

The reason this error message is useful is that it prompts me to think about what I’m attempting to do – I’ve been prompting the user to sign into the nicksdemodir.onmicrosoft.com tenant, which is fine if I’m a user that belongs to that tenant but since I’m attempting to use a different user, this is clearly not correct. So, the first step in making my application multi-tenanted is to change the authorization url that I’m directing the user to in order to sign in, to one that is more generic and will allow signing in by users from any tenant. This involves exchanging the “nicksdemodir.onmicrosoft.com” with “common” in the url – the following code shows how I adapted the code in my sample application to support urls that are single tenanted (ie AuthorizationUrl and AdminConsentUrl) as well as the multi-tenanted equivalent (ie MultiTenantAuthorizationUrl and MultiTenantAdminConsentUrl).

private string BaseAuthorizationUrl =>
    "
https://login.microsoftonline.com/{0}/oauth2/authorize?" +
    "client_id=40dba662-4c53-4154-a5cf-976473306060&" +
    "response_type=code&" +
    "redirect_uri=sample://callback&" +
    "nonce=1234&" +
    "resource=
https://graph.windows.net";

private string AuthorizationUrl => string.Format(BaseAuthorizationUrl, "nicksdemodir.onmicrosoft.com");

private string AdminConsentUrl => $"{AuthorizationUrl}&prompt=admin_consent";
private string MultiTenantAuthorizationUrl => string.Format(BaseAuthorizationUrl, "common");
private string MultiTenantAdminConsentUrl => $"{MultiTenantAuthorizationUrl}&prompt=admin_consent";

For example:

Authorization url: https://login.microsoftonline.com/nicksdemodir.onmicrosoft.com/oauth2/authorize?client_id=40dba662-4c53-4154-a5cf-976473306060&response_type=code&redirect_uri=sample://callback&nonce=1234&resource=https://graph.windows.net

Multi-tenant authorization url: https://login.microsoftonline.com/common/oauth2/authorize?client_id=40dba662-4c53-4154-a5cf-976473306060&response_type=code&redirect_uri=sample://callback&nonce=1234&resource=https://graph.windows.net

Attempting to sign in using the multi-tenant authorization url with an account that doesn’t belong to the nicksdemodir.onmicrosoft.com tenat now yields the following error:

image

This error seems to be correct, considering the application registration exists in the nicksdemodir.onmicrosoft.com tenant. Unfortunately it’s not very clear what you need to do in order to fix this issue – you can’t add the application to the btro365dev.onmicrosoft.com tenant, and even if you could, you wouldn’t want to have to manually do that for every tenant that you want to support. Luckily, there is a mechanism that allows Azure AD to essentially add the application to new tenants on an as required basis (similar to how applications are added to a users list of applications at https://myapps.microsoft.com as they consent to use of the application). In order for Azure AD to do this, the application registration has to be configured to support multiple tenants. Click on the Manifest button for the application registration in Azure AD – the property “availableToOtherTenants” should be set to true (default is false).

image

Now when we attempt to sign in (again with a non-global administrator user) we see a familiar error saying that the calling principal (ie the signed in user) doesn’t have permissions.

image

We know how to fix this from my previous post, the only difference is that we need to direct the user to the multi-tenant admin consent url eg

https://login.microsoftonline.com/common/oauth2/authorize?client_id=40dba662-4c53-4154-a5cf-976473306060&response_type=code&redirect_uri=sample://callback&nonce=1234&resource=https://graph.windows.net&prompt=admin_consent

The global administrator, after signing in, will again see the admin consent prompt – it’s worth pointing out here that it lists both the directory the user is signed into (ie BTR Office Dev – btro365dev.onmicrosoft.com) and the tenant that the application is published (ie registered) in (ie DemoDirectory – nicksdemodir.onmicrosoft.com).

image

Again, consenting will enable all users in the foreign tenant (ie btro365dev.onmicrosoft.com) to then access the application via the multi-tenant authorization url.

There is one last adjustment that has to be made, and that’s to the Token url. When exchanging the code for an access token, it’s important that the token url is also adjusted to be either single or multi-tenant. Previously the url included the tenant that the application was registered to ie nicksdemodir.onmicrosoft.com. This needs to be changed in the multi-tenant scenario to use “common”. In order to allow authorization to occur for both single and multi-tenant scenarios within the application, I needed a way to dynamically control the token url based on whether the user signed in via the single tenant or multi-tenant authorization url. Currently, all we get back when the user has signed in is a code which we need to exchange for an access token. Luckily, we can pass an additional parameter, “state,” into the authorization url, which will get passed back to the application along with the code – we can use this to determine which authorization url was used. I’m only going to adjust the multi-tenant authorization url as the application will treat the lack of state parameter to mean that the user was directed to the single tenant authorization url.

private string MultiTenantAuthorizationUrl => string.Format(BaseAuthorizationUrl, "common") + "&state=multi";
private string MultiTenantAdminConsentUrl => $"{MultiTenantAuthorizationUrl}&prompt=admin_consent";

Now, the token url is updated based on the state parameter value:

private string BaseTokenUrl => "https://login.microsoftonline.com/{0}/oauth2/token";
private string TokenUrl(bool isMulti)
{
    return string.Format(BaseTokenUrl, isMulti ? "common" : "nicksdemodir.onmicrosoft.com");
}

var isMulti = uri?
                    .Split('?').Skip(1).FirstOrDefault()?
                    .Split('&').Select(q => q.Split('='))
                    .Where(x => x.Length == 2 && x[0] == "state")
                    .Select(x => x[1])
                    .FirstOrDefault() == "multi";

var tokenUrl = TokenUrl(isMulti);

And that’s it – a user can sign in from any tenant (assuming the global administrator has signed in an consented) and retrieve information from the Azure Graph API.

Admin Consent for Permissions in Azure Active Directory

In the previous posts I’ve discussed authenticating and authorizing a user with Azure Active Directory (Azure AD) using a basic application registration. All application registrations are given default permissions to access the Azure Graph API – this was used in my previous post to retrieve information about the signed in user. The default permission set is a delegated permission that allows the user to sign in and view their own profile. This can be viewed in the Azure portal by extending the Required permissions tab for the application.

image

In this post I’m going to extend this permission set to include the “Read directory data” permission. You’ll notice in the previous image that there is a green tick in the “Requires Admin” column. What this means is that in order for a regular user (ie a user that is not a global administrator for the tenant) to sign in, a global administrator must first sign in and consent to permission on behalf of the organisation. If a regular user attempts to sign in, they’ll be confronted with an error message such as:

image 

Essentially the error “AADSTS90093: Calling principal cannot consent due to lack of permissions” indicates that a global administrator needs to sign in an consent on behalf of the organisation before users can sign in. If a global administrator signs in, they’ll see a prompt where they can consent permissions – this is slightly confusing as it would imply that the administrator is consenting on behalf of the organisation. Unfortunately this is not the case, they’re only consenting for use by their account.

image

In order for a global administrator to consent on behalf of an organisation, so that all users can make use of the “admin consent” permissions, they have to be directed to a new sign in page with the parameter “prompt=admin_consent” set in the query. In other words, the admin consent url is exactly the same as the authorization url, except it has “&prompt=admin_consent” appended to the end.

https://login.microsoftonline.com/nicksdemodir.onmicrosoft.com/oauth2/authorize?client_id=40dba662-4c53-4154-a5cf-976473306060&response_type=code&redirect_uri=sample://callback&nonce=1234&resource=https://graph.windows.net&prompt=admin_consent

The admin consent prompt looks slightly different to a regular consent prompt as it highlights that consent is going to be assigned for the entire organisation

image

As this is a one-off operation, a global administrator can either navigate to the url in the browser, or the application can have a separate button that would launch the url so that the admin can consent. After the global administrator has consented, user’s will still be prompted to consent but this is for the delegated permission. In the same way that user permissions can be revoked by going to https://myapps.microsoft.com and deleting the application entry, organisation permissions can be revoked by opening the Enterprise applications tab for the Active Directory in the Azure portal. Select the application you want to remove and click the Delete button.

image

After the global administrator has consented for the organisation, any user can then read the directory data (ie more than just their own profile).

Verifying Azure Active Directory JWT Tokens

When working with OAuth and Open ID Connect, there are times when you’ll want to inspect the contents of id, access or refresh tokens. The website https://jwt.io is useful as you can drop in the token in the pane on the left, and the site dynamically decodes the header, body and signature for the JWT.

image

Unfortunately by itself the signature on the JWT can’t be verified as the website doesn’t know what key to use to validate the signature. The header of the JWT does provide information about the algorithm used (ie RS256) and the id of the key used but this by itself isn’t enough to locate the key to be used.

image

As RS256 is a public/private key algorithm, there is a private key, which the issuer holds, and a public key which is available to anyone to access. The former is used to generate the signature for a JWT; the later can then be used to validate the signature. To find the public key to use to validate the signature I’ll start with the OpenID Connect configuration document, which is available for any tenant at:

https://login.microsoftonline.com/{tenantId}/.well-known/openid-configuration

eg https://login.microsoftonline.com/nicksdemodir.onmicrosoft.com/.well-known/openid-configuration

The returned configuration document contains an attribute, jwks_uri, which points at https://login.microsoftonline.com/common/discovery/keys

image

Loading the jwks_uri returns another JSON document which lists a number of keys. Now we can use the kid from the header of the JWT to identify which key to use, in this case the first key in the list.

image

Attempting to simply copy the x5c value from the list of keys into the Public Key or Certificate box on the jwt.io website will still not verify the signature of the JWT. In order to verify the signature, wrap the key in BEGIN and END CERTIFICATE markers as follows:

-----BEGIN CERTIFICATE-----
MIIDBTCCAe2gAwIBAgIQEsuEXXy6BbJCK3bMU6GZ/TANBgkqhkiG9w0BAQsFADAtMSswKQYDVQQDEyJhY2NvdW50cy5hY2Nlc3Njb250cm9sLndpbmRvd3MubmV0MB4XDTE2MTEyNjAwMDAwMFoXDTE4MTEyNzAwMDAwMFowLTErMCkGA1UEAxMiYWNjb3VudHMuYWNjZXNzY29udHJvbC53aW5kb3dzLm5ldDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKd6Sq5aJ/zYB8AbWpQWNn+zcnadhcMYezFvPm85NH4VQohTm+FMo3IIJl6JASPSK13m9er3jgPXZuDkdrEDHsF+QMEvqmffS2wHh3tKzasw4U0jRTYB0HSCbmnw9HpUnv/UJ0X/athO2GRmL+KA2eSGmb4+5oOQCQ+qbaRXic/RkAOLIw1z63kRneLwduQMsFNJ8FZbWkQFj3TtF5SL13P2s/0PnrqwGD59zcbDu9oHOtciu0h++YhF5CWdWEIgafcZk9m+8eY12BKamvPdBnyfpz6GVTenJQe2M+AGz5RSNshvI976VUbBiaIeNzvzaG91m62kFWLRqE3igq6D02ECAwEAAaMhMB8wHQYDVR0OBBYEFAgoZ9HLgFxH2VFGP6PGc4nFizD2MA0GCSqGSIb3DQEBCwUAA4IBAQBSFXalwSJP/jihg04oJUMV2MTbuWtuFhdrdXiIye+UNc/RX02Q9rxd46BfGeKEBflUgNfEHgyEiWTSLAOSDK70vu+ceCVQCGIQPjnGyYOpm80qAj/DNWZujVcSTTV3KZjMFsBVP7miQowfJQ58u9h8yuJHNhPpB2vOFmNhm4uZq3ve529Xt51HdtQGG9+Z9n1DhObqzkbz8xEFjA+KdfcRsZXa14ZkpAOe35VgyY0f8x34Y0LPfibWcNpfp0AhxKzyqT1GRRlKTjiBA6WNJIJIEeqh/nfOnwM0UQKRnt+2qeV3u00a5lrvJtEy7nq+s7xYtpVAsCvn5T0U1/8IHkxt
-----END CERTIFICATE-----

Entering the wrapped key into the Public Key or Certificate box on the jwt.io website will successfully verify the signature of the JWT.

image

Authorizing Access to Resources using Azure Active Directory

In my previous post I discussed authenticating a user using Azure Active Directory (Azure AD), returning an id_token that can be used to identify the user that has signed in. However, this token isn’t an access token and as such can’t be presented in order to access remote services. In this post I’m going to show how you can request an access token that can be presented in the Authorization header when calling a service. The workflow is very similar to the workflow to retrieve the id_token:

- User attempts to sign into an application

- Application launches the Authorize URL in an external browser (includes “resource” parameter in Authorize URL)

- User is directed to a Microsoft URL where they are prompted to sign in

- User signs in

- User is prompted to consent that the application can access the specified resource

- After sign in, the User is redirected back to the application via a custom protocol

- Application receives an authorization code

- Application performs a POST request to the Token URL in order to exchange authorization code for an access token

- Application receives the access token

- Application makes call to remote service, attaching the access token in the Authorization header

To demonstrate this workflow I’m going to adapt the sample application I created in my previous post in order to access the Azure Graph API. The sample application is already configured with access to the Azure Graph API – this is done by default for all application registrations. In order to request access to a resource, you need to know the url of the resource you want to access. In this case the url for the Azure Graph API is https://graph.windows.net.

In addition to including the resource url in the authorization url, the other change I need to make is to switch the response type from id_token to code. The updated authorization url is:

var  authorizationUrl=
    "https://login.microsoftonline.com/nicksdemodir.onmicrosoft.com/oauth2/authorize?" +
    "client_id=40dba662-4c53-4154-a5cf-976473306060&" +
    "response_type=code&" +
    "redirect_uri=sample://callback&" +
    "nonce=1234&" +
    "resource=https://graph.windows.net";

Launching this url in the external browser will again prompt the user to sign in (unless they have previously signed in for this application, such as if you followed my previous post) but rather than immediately being redirected back to the application, the user will see a consent prompt – you’ll note that similar to the sign in prompt, the name of the application specified in Azure AD is used when requesting permissions.

image

The other thing to note is that once you’ve consented permissions for the application, you won’t be prompted again – Azure AD remembers that you’ve granted permissions. Permissions can be revoked by going to https://myapps.microsoft.com, selecting the application and clicking Remove.

image

The same “Remove” option is available if you turn on the new look (it’s the same url to get there – https://myapps.microsoft.com)

image

After completing the sign in and consent workflow, the user is navigated back to the application using the custom protocol. This time, instead of an id_token, the application receives a code as part of the url:

sample://callback/?code=AQABAAAAAADRN…….L7YiQ7PIAA&session_state=ffffd83b-3820-489e-9f35-70e97d58fd04

Unlike the id_token, and as you’ll see soon, the access_token, the code is not a jwt token that you can interrogate for information about the signed in user. Instead the next step in the process is to do the code-token exchange to retrieve the required access token. This involves doing a POST request to the Token URL, passing parameters in the body of the request.

Token URL: https://login.microsoftonline.com/{tenantId}/oauth2/token

eg https://login.microsoftonline.com/nicksdemodir.onmicrosoft.com/oauth2/token

The POST body needs to contain the following values:

var postBody = new Dictionary<string, string>
{
    {"grant_type", "authorization_code"},
    {"client_id", "40dba662-4c53-4154-a5cf-976473306060"},
    {"redirect_uri", "sample://callback"},
    {"resource", "https://graph.windows.net"},
    {"code", code}
};

40dba662-4c53-4154-a5cf-976473306060 – This is the client id (aka application id) of the application registration in Azure AD

sample://callback – This is the redirect uri specified in the application registration

https://graph.windows.net – This is the resource that you’re requesting an access token for. Make sure this is the URL for the Azure Graph API, not to be confused with the Microsoft Graph API (https://graph.microsoft.com)

code – This is the actual code that is returned from the sign in process (ie don’t use the word “code”)

The resulting code for parsing the code from the application redirect, and then exchange for an access token is as follows:

protected override async void OnActivated(IActivatedEventArgs args)
{
    base.OnActivated(args);
    if (args.Kind == ActivationKind.Protocol)
    {
        var eventArgs = args as ProtocolActivatedEventArgs;

        var uri = eventArgs.Uri.AbsoluteUri;
        var code = uri?
                    .Split('?').Skip(1).FirstOrDefault()?
                    .Split('&').Select(q => q.Split('='))
                            .Where(x=>x.Length==2 && x[0]=="code")
                            .Select(x=>x[1])
                            .FirstOrDefault();

        var tokenUrl = "https://login.microsoftonline.com/nicksdemodir.onmicrosoft.com/oauth2/token";
        var postBody = new Dictionary<string, string>
        {
            {"grant_type", "authorization_code"},
            {"client_id", "40dba662-4c53-4154-a5cf-976473306060"},
            //{"redirect_uri", "sample://callback"},
            {"resource", "
https://graph.windows.net"},
            {"code", code}
        };
        using (var client = new HttpClient())
        {
            var content = new FormUrlEncodedContent(postBody);
            var result = await client.PostAsync(tokenUrl, content);
            var resultContent = await result.Content.ReadAsStringAsync();
        }
    }
}

The resultContent variable will include a JSON string which consists of an access_token, refresh_token etc.

image

In order to extract the access_token, the resultContent can be deserialized to an entity:

public class TokenData
{
    public string expires_in { get; set; }
    public string access_token { get; set; }
    public string refresh_token { get; set; }
    public string id_token { get; set; }
}

var resultContent = await result.Content.ReadAsStringAsync();
var token =  JsonConvert.DeserializeObject<TokenData>(resultContent);

Finally, the token.access_token value can be used to make a call to the Azure Graph API:

var graphUri = "https://graph.windows.net/me?api-version=1.6";
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer",token.access_token);
var graphProfile = await client.GetStringAsync(graphUri);

The following screenshot shows the resulting profile information that’s returned from the Graph API

image

Note that the access token is relatively short lived. The refresh token can be used to renew the access token or to retrieve an access token for an alternative resource.