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

Xamarin Live Player from Build 2017

Microsoft’s Build conference is over for another year and I’m still working my way through the various sessions. I did however get a chance to take a look at the Xamarin Live Player (https://developer.xamarin.com/guides/cross-platform/live/player/) which is an interesting announcement and one that can help reduce the friction of getting pre-release applications onto devices. The Live Player is in preview, which means you’ll need the preview version of Visual Studio, the updated Xamarin bits and the alpha channel Xamarin bits on your Mac build machine (for those of you doing development on Windows). I highly recommend following all the setup instructions - https://developer.xamarin.com/guides/cross-platform/live/install/.

Getting the Live Player setup and running was relatively straight forward, after I fixed up my Mac build machine because it was missing certificates/provision profile etc. I was able to install the Live Player on both my iPhone and a test Android device. After creating a simple Xamarin Forms project in Visual Studio, the Live Player is available from the device dropdown.


After clicking run with the Live Player selected, the following dialog is displayed. Launch the Live Player app on your test device. You can either scan the QR code, or you can enter the code presented within the app into the dial.

After scanning the QR code, a connection is established between the Live Player app running on your device and the instance of Visual Studio. A new entry should appear in the devices dropdown with your device name followed by the word Player.

Now that you’ve associated your device, each time you want to run the application on your device, you can simply select the appropriate player from the devices dropdown and hit run. The app takes a second or two to deploy and will appear on your device – this provides a very quick way for you to deploy and test applications, particularly on an iOS device when doing development on a Windows machine.

I can definitely see the advantage of using the Live Player but it had a few limitations (https://developer.xamarin.com/guides/cross-platform/live/limitations/) so I’m not sure how effective it will be until they resolve some of these.

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.

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.

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 admin@nicksdemodir.onmicrosoft.com. 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 testuser@btro365dev.onmicrosoft.com). 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 admin@btro365dev.onmicrosoft.com 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.

Authenticating an Application using Azure Active Directory

In my previous post I discussed in brief the use of the OAuth Authorization Code workflow and the corresponding endpoints. As a brief recap, the workflow I’ll going to walk through is the following:

- User attempts to sign into an application

- Application launches the Authorize URL in an external browser

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

- User signs in

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

- Application receives the token containing information about the user that has signed in

In this walk through I’ll use a UWP application but the workflow works well for any platform that supports custom protocol. Before I get started I’m going to need a few things:

Authorize URL - https://login.microsoftonline.com/{tenantId}/oauth2/authorize
Tenant Id - nicksdemodir.onmicrosoft.com (this can also be specified as a guid)

Next, I’m going to register an application with Azure Active Directory (Azure AD). You can think of this registration as identifying the application that is going to connect to Azure AD. In the Azure portal, open the Active Directory management pane and select App registrations

image

At the top of the app registrations pane, click the Add button. In the Create form I’ll give the application registration a name (the name is used both in the Azure portal as well as on the sign in page when a user is signing into the application). The application type needs to be set to Native – this allows the application to exchange an Authorization Code for an Access Token without having to provide a client secret.

image

The final property is the Redirect URI, which is the URL that the browser will be directed to after the user has signed in. In this case I’m specifying a custom protocol which will be used to redirect back to the application. Once the application registration is complete I can copy the Application Id from the application pane.

image

I have all the information I need in order to authenticate a user; all I need to do is form the authorization url that will be launched in the external browser:

private async void AuthenticateClick(object sender, RoutedEventArgs e)
{
    var  authorizationUrl=
        "
https://login.microsoftonline.com/nicksdemodir.onmicrosoft.com/oauth2/authorize?" +
        "client_id=40dba662-4c53-4154-a5cf-976473306060&" +
        "response_type=id_token&" +
        "redirect_uri=sample%3A%2F%2Fcallback&" +
        "nonce=1234";
    await Launcher.LaunchUriAsync(new Uri(authorizationUrl));
}

There are various components to the authorization url:

nicksdemodir.onmicrosoft.com – The tenant where the application is registered. Alternatively use “common” for multi-tenanted applications.

0dba662-4c53-4154-a5cf-976473306060 – This is the Application ID (also referred to as the client ID) of the application registration in Azure AD

id_token – This is the requested response, which in this case is a JWT token that represents information about the user. When using OAuth to authorize access to a resource, either specify “code” or “code id_token”.

sample://callback – This is the url that the browser will be redirected to after the sign in process has been completed.

1234 – This is a application specific nonce which can be used to ensure the returned token matches the authentication request from the application.

In order for the user to be redirected back to the UWP application the “sample” custom protocol needs to be registered to the application. For a UWP application this is done by adding the following XML to the package.appxmanifest, immediately after the closing VisualElements tag.

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="sample">
      <uap:Logo>assets\StoreLogo.png</uap:Logo>
      <uap:DisplayName>Sample</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
</Extensions>

In the App.xaml.cs file for the application, the OnActivated method needs to be overridden. This method will be invoked when the user is switched back to the application after signing in. The args property can be interrogated in order to retrieve the id_token that has information about the authenticated user.

image

The site http://jwt.io can be used to pull apart the id_token which shows the name of the user that’s signed in. It also shows the nonce which the application can match with the nonce specified in the authentication request.

image

In this post I’ve shown how you can use Azure Active Directory to authenticate a user. Note however, this is not enough to authorize a user for access to any resources. In the next post I’ll walk through using OAuth to authorize user access to a resource.

Azure Active Directory and Google OAuth 2.0 Endpoints

There are a lot of arguments for and against using pre-built SDKs for doing OAuth authentication with Azure AD and Google. Having worked with the ADAL library for Azure quite a bit I think the team have done a reasonable job, especially considering it now works across the three mobile platforms (iOS, Android and Windows), and works with a PCL that is .NET Standard based. However, using any library does force you into working within the bounds of the library. For example, we recently found two shortcomings in the library:

- It doesn’t provide a good solution for doing a browser based workflow for signing in – instead it uses a webview hosted within the context of the application (depending on the platform this may be augmented with more security, for example the Web Authentication Broker - https://msdn.microsoft.com/en-us/library/windows/apps/windows.security.authentication.web.webauthenticationbroker.aspx). A browser based workflow involves launching the external browser for the user to sign in; upon successful sign on, the user is redirected back to the app.

- It doesn’t provide a mechanism to clear cached credentials. Whilst the tokens can be cleared, this doesn’t clear the cookies held within the hosted webview, which can lead to issues if the application is multi-tenanted.

If the provided libraries don’t align with what you want, you may have to roll your own solution. The Authorization Code workflow requires two endpoints:

- Authorize URL – this is the URL that you navigate the user to in order for them to sign into your application. After signing in an Authorization Code is returned to the application

- Token URL – this is the URL that the application does a POST request to in order to convert the Authorization Code into an access token.

For Azure Active Directory, these endpoints are:

Authorize - https://login.microsoftonline.com/{tenantId}/oauth2/authorize

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

For Google, these endpoints are:

Authorize - https://accounts.google.com/o/oauth2/v2/auth

Token - https://www.googleapis.com/oauth2/v4/token

As both services conform to OAuth/OpenID Connect, the parameters are the same, although there are some variations on the values that you need to supply for scope and client id.

Useful OAuth, OpenID Connect, Azure Active Directory and Google Authentication Links

Over the past couple of weeks I’ve been assisting with the development work of an enterprise system that uses both Azure Active Directory (Azure AD) and Google to authenticate users. It’s a cross platform solution which means we need code that works across both authentication platforms, and the three mobile platforms. Unfortunately this is easier said than done – The Azure AD team have done a reasonable job with the ADAL library but it’s not like we can repurpose that library for authenticating against Google. This is a tad annoying since both Azure AD and Google both use OAuth and OpenID Connect, so you’d expect there to be a good library that would work across both.

In trying to find a workable solution I can across a number of links that I want to bookmark here for future reference:

OAuth 2

Home - https://oauth.net/2/

The OAuth home page is a good starting point if you want to get more links and information about OAuth (1 and 2) but I actually found it’s main use for me was to point at the OAuth 2.0 Framework RFC

OAuth 2.0 Framework RFC - https://tools.ietf.org/html/rfc6749

You can think of the OAuth 2.0 Framework RFC as being the specification for OAuth 2.0. There are some extensions and other standards that relate to OAuth 2.0 but this is a must read if you want to understand what OAuth 2.0 is all about. You may need to refer back to this when reading other blogs/tutorials as it can help clarify what each of the roles and responsibilities are in the process.

Simple overview of OAuth 2 - https://aaronparecki.com/2012/07/29/2/oauth2-simplified

This overview provides a quick summary of the various flows for OAuth 2.0. However, I disagree with the use of the implicit workflow for mobile applications. Whilst mobile applications are not “trusted,” which would normally imply the use of the implicit workflow, the reality is that the implicit workflow can’t issue refresh tokens. This means that unless you want your users to have to log in each time they use your mobile application, you need to use the Authorization Code workflow (the client secret shouldn’t be required when requesting access tokens for mobile apps – this depends on which authentication provider you’re using).

 

OpenID Connect

Home - http://openid.net/connect/

The OpenID Connect home page is again a good starting point as it links to the many different parts of the OpenID Connect standard. OpenID Connect builds on top of OAuth 2.0 in order to provide a mechanism for users to be authenticated as well as authorized for resource access. In addition to the creation of access tokens, OpenID Connect defines an id_token which can be issued in absence of any resource that is just used to identify the user that has authenticated.

OpenID Connect Core 1.0 - http://openid.net/specs/openid-connect-core-1_0.html

This is the core specification of OpenID Connect. Similar to the specification for OAuth, this is worth both a read and to be used as a reference when working with OpenID Connect implementations.

OpenID Connect Session Management 1.0 - http://openid.net/specs/openid-connect-session-1_0.html

Whilst still in draft this standard covers how implementers are supposed to handle log out scenarios, which is useful as your application can’t simply delete it’s access tokens when a user opts to log out. Ideally when a user logs out, you’d want to make sure both cached tokens are cleared, along with invalidating any access or refresh tokens.

 

Google

OAuth 2.0 Overview - https://developers.google.com/identity/protocols/OAuth2

OpenID Connect - https://developers.google.com/identity/protocols/OpenIDConnect

Google’s documentation isn’t too bad but does require you to read all of the pages as the OAuth and OpenID Connect implementation details seem to be scattered across the pages. The assumption is that for any given type of application you can simply read the one page – unfortunately, if you want to get an understanding of the Google implementation, you really need to read everything. Authenticating/authorizing with Google is significantly simpler than with Azure AD as there is no notion of linking your application registration with specific permissions to other applications registered with Azure AD. This is a significant limitation of using Google sign in, as you can really only use it to authenticate and then use the token to access various Google APIs.

 

Azure Active Directory

Azure AD Developer’s Guide - https://docs.microsoft.com/en-au/azure/active-directory/develop/active-directory-developers-guide

Authentication Scenarios for Azure AD - https://docs.microsoft.com/en-au/azure/active-directory/develop/active-directory-authentication-scenarios

Azure AD is a much longer read, and it’s very easy to get lost in the world of application configuration and settings. My recommendation is to start with something simple, and then grow from that. For examples, start by authenticating a use to sign into your mobile app, then extend it so that you can use the access token to connect to a Web API, and then on to retrieve information from other Microsoft services within the Web API, and then perhaps make it all multi-tenanted (that’s one for another post!).

NuGet does my head in….. No thanks to Xamarin.Forms

This is a bit of a rant with hopefully a fix that will help others. Firstly, the rant:

In my post on Building Cross Platform Apps I used the new project templates in Visual Studio 2017 to create a new Xamarin.Forms application that targets iOS, Android and UWP. What I didn’t mention is the time I wasted trying to upgrade NuGet packages in order to get the thing to build and run. Namely I get the following exception when attempting to build the newly created application.

Severity    Code    Description    Project    File    Line    Suppression State
Error        Exception while loading assemblies: System.IO.FileNotFoundException: Could not load assembly 'Xamarin.Android.Support.v7.RecyclerView, Version=1.0.0.0, Culture=neutral, PublicKeyToken='. Perhaps it doesn't exist in the Mono for Android profile?
File name: 'Xamarin.Android.Support.v7.RecyclerView.dll'
   at Java.Interop.Tools.Cecil.DirectoryAssemblyResolver.Resolve(AssemblyNameReference reference, ReaderParameters parameters)
   at Xamarin.Android.Tasks.ResolveAssemblies.AddAssemblyReferences(DirectoryAssemblyResolver resolver, ICollection`1 assemblies, AssemblyDefinition assembly, Boolean topLevel)
   at Xamarin.Android.Tasks.ResolveAssemblies.Execute(DirectoryAssemblyResolver resolver)    App5.Droid           

I figured that there was something wrong with the Xamarin.Forms and/or Xamarin Android NuGet packages, so I thought I’d just go an upgrade the Xamarin.Forms NuGet package. Note: Don’t every try to upgrade the Xamarin Android packages independently – let the Xamarin.Forms NuGet package determine which versions of those libraries you need. Anyhow, unfortunately that just generates another exception:

Severity    Code    Description    Project    File    Line    Suppression State
Error        Unable to resolve dependencies. 'Xamarin.Android.Support.Compat 24.2.1' is not compatible with 'Xamarin.Android.Support.Design 24.2.1 constraint: Xamarin.Android.Support.Compat (= 24.2.1)'.            0   

At this point I was starting to get annoyed – it looks like there was already an inconsistency between the Xamarin.Forms package and the Xamarin Android packages included in the template. Luckily it was easier to fix than I thought it was. I opened up the packages.config file for the Android head project and delete the Xamarin.Android libraries.

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Xamarin.Android.Support.Design" version="23.4.0.1" targetFramework="monoandroid60" />
  <package id="Xamarin.Android.Support.v4" version="23.4.0.1" targetFramework="monoandroid60" />
  <package id="Xamarin.Android.Support.v7.AppCompat" version="23.4.0.1" targetFramework="monoandroid60" />
  <package id="Xamarin.Android.Support.v7.CardView" version="23.4.0.1" targetFramework="monoandroid60" />
  <package id="Xamarin.Android.Support.v7.MediaRouter" version="23.4.0.1" targetFramework="monoandroid60" />

  <package id="Xamarin.Forms" version="2.3.2.127" targetFramework="monoandroid60" />
</packages>

Then, I just upgraded Xamarin.Forms to the latest NuGet package and all was good again. Lastly, I upgraded all the other NuGet packages (excluding the Xamarin.Android packages) to the latest stable versions.