DEV Community: Yuri Burger

Azure Active Directory B2C With PKCE for Your Angular App

Yuri Burger — Mon, 09 Nov 2020 21:08:39 +0000

Let's create and integrate an Angular app with Azure Active Directory Business to Consumers using the Authorization Code with Proof Key of Code Exchange flow.

Although this post works with an Angular App, the concepts (including the twists and tweaks) needed to make it work for Azure AD B2C are universal for Single Page Applications. So even if you have Vue or React, this post could be useful.

Why this post (and why not just use the well known Implicit flow)? The browser based Implicit flow is old and The OAuth Working Group has published a document recommending replacing the Implicit flow with the newer Authorization Code flow with Proof Key for Code Exchange (we like to simply refer to it as the PKCE flow).

Azure AD B2C still supports the Implicit flow (as it has for a long time) but it recently began to recommend the PKCE based flow when creating new apps. So now seems like the perfect time to go along with this and start using it too. This blogpost should get you up and running for new apps, but refactoring apps that worked with the Implicit flow shouldn't be too hard. If you happen to use one of the OpenID Connect certified libraries, the changes to your apps codebase are minimal!

But what is this new PKCE flow? It is basically an enhanced version of the Authorization Code flow. To illustrate, follow me through steps in the diagram. This flow is not complex, but understanding this will benefit you if you ever need to troubleshoot login issues.

The user clicks a login link or button. The app generates a random code_verifier and derives a code_challenge from that verifier.
The app then redirects the user to the Azure AD B2C Authorize endpoint with the code_challenge.
The user is redirected to the login page. After supplying the correct credentials the user is redirected back to the app with a authorization code.
The app receives the code and posts this code along with the code_verifier (from step 1) to the Azure AD B2C Token endpoint to request an access and id token. After validation Azure AD B2C sends both these tokens back to the app.
The user can now request data from the API and the app will send the access token with the request.

Setting up the stage (on Azure AD B2C)

This is a complete walkthrough, so contains a lot of steps. If you already have a working Azure AD B2C setup, skip to the next part.

First we register a new application. Two things are important, the rest can be left with the defaults:

Supported account types must be the option that enables the user flows
The Redirect URI must be of type Single-page-application (SPA) otherwise we would not have PKCE enabled and instead need to fallback on the Implicit flow.

After we create the application, we need to enter any additional Redirect URIs we require. In case of this demo, we add http://localhost:4200/index.html as this matches our Angular development setup.

To be able to request access tokens, we need to setup and expose an API using a scope. Start by "Exposing an API" and setting a App ID URI. This needs only to be done once and the URI must be unique within your Azure AD B2C tenant.

After the URI we can continue adding API scope(s).

Before we can actually request an API scope, the permissions must be added. API Permissions, Add a permission, My APIs
And, because we want to skip the consent forms, we grant admin consent for this permission.

And finally we take note of the Application (client) ID from the overview page. We need this value later configuring our Angular app.

Setting up the User Flows (on Azure AD B2C)

User Flows are configurable login/logout/reset experiences. They are (somewhat) customizable and provide us with ready to go multi-language templates for our users. So we set up two of them:

First a flow for signing up (registration) and signing in (login). This flow enables both in one universal form.

In my case I enable the Local Accounts, so the user objects will be stored in my Azure AD B2C tenant.

The second flow enables self-service password reset. This flow requires some tweaking in our app, but that is covered in the last part.

Since we have Local Accounts, we enable that option.

Setting up your app (with Angular)

There are a few OAuth/OpenID Connect Angular libraries out there, but for my projects (including this demo) I have picked the excellent library from Manfred Steyer. Just follow the "Getting Started" documentation or take a look at the demo app.

More info: https://manfredsteyer.github.io/angular-oauth2-oidc/docs/index.html

Couple of things are important:

You need the clientid from the new Azure AD B2C app that was created earlier;
You also need the custom scope from that was created together with the app;
We need a additional steps to be able to succesfully login with PKCE. See the next section for this.

The twist and tweaks with Azure AD B2C

Up until this point, things are pretty straightforwared. And if you were to run this example on any of the other well known Identity Service Providers, you would be finished after completing the previous part. For Azure AD B2C we need to do some additional configuration and coding to make things work well.

Issue 1: disable strict document validation

The mentioned library uses a feature called strictDiscoveryDocumentValidation by default. This ensures that all of the endpoints provided via the Identity Provider discovery document share the same base URL as the issuer parameter. Azure AD B2C provides different domains or paths for various endpoints and this makes the library fail validation. To use this library with Azure AD B2C we need to disable this document validation.

There is a property for this in the AuthConfig, just set the "strictDiscoveryDocumentValidation: to "false"

Issue 2: support the password reset flow

This one ended up being pretty ugly, especially for the PKCE flow. So what's the deal?

Microsoft uses a feature called Linking User Flows. What happens is, that if you click the "Forgot password" option in the login form, Microsoft will redirect the user back to your app with a special error code.

A sign-up or sign-in user flow with local accounts includes a Forgot password? link on the first page of the experience.
Clicking this link doesn't automatically trigger a password reset user flow. Instead, the error code AADB2C90118 is returned to your application. Your application needs to handle this error code by running a specific user flow that resets the password.

So we need to ensure that if a user has clicked the Forgot Password link, we send them on the right path back to Azure AD B2C. Ok, that is where the second flow we created comes into play. This flow has exactly the same base URL but uses a different profile. In our case "b2c_1_passwordreset" instead of "b2c_1_signupandsignin". We do this by noticing the error code and overriding the authorize endpoint:



if (this.userHasRequestedPasswordReset(err)) {
    // In this case we need to enter a different flow on the Azure AD B2C side.
    // This is still a valid Code + PKCE flow, but uses a different form to support self service password reset
    this.oauthService.loginUrl = this.oauthService.loginUrl.replace(
        'b2c_1_signupandsignin',
        'b2c_1_passwordreset'
    );

    this.oauthService.initCodeFlow();
}

private userHasRequestedPasswordReset(err: OAuthErrorEvent): boolean {
    return (err.params['error_description'] as string).startsWith(
      'AADB2C90118'
    );
}

This will make sure a user gets directed back to Azure and into the correct flow. If a user now resets their password, they get directed back to your app with the code and our app can fetch the access token and id token.

But our app breaks. :'(

I will leave out most of the gory details, but what happens is that our app "sees" the code coming in and starts the code exchange part of the flow (see step 3 in the diagram above). It does that using the default AuthConfig and performs a POST to the default/configured 'b2c_1_signupandsignin' profile endpoint. But our code challenge was done on the 'b2c_1_passwordreset' endpoint and thus Azure throws a "HTTP4xx you screwed up" error. To fix that, we need to make sure that in the case of reset-password, we override the profile on the token endpoint (like we did on the authorize endpoint earlier). This is not that difficult, because we can send a "state" along with our requests. On the way back we will pick up this state and if it is present, we fix the token endpoint:



this.oauthService
  .loadDiscoveryDocument(url)
  .then((_) => {
    if (this.userHasEnteredPasswordResetFlow()) {
      // We need to change to token endpoint to match the reset-password flow
      this.oauthService.tokenEndpoint.replace(
        'b2c_1_signupandsignin',
        'b2c_1_passwordreset'
      );
    }

    return this.oauthService.tryLoginCodeFlow();
  })
  .then((_) => {
    if (!this.oauthService.hasValidAccessToken()) {
      this.oauthService.initCodeFlow();
    }
  })
  .catch((err) => {
    if (this.userHasRequestedPasswordReset(err)) {
      // In this case we need to enter a different flow on the Azure AD B2C side.
      // This is still a valid Code + PKCE flow, but uses a different form to support self service password reset
      this.oauthService.loginUrl = this.oauthService.loginUrl.replace(
        'b2c_1_signupandsignin',
        'b2c_1_passwordreset'
      );
      // Add this to the state as we need it on our way back
      this.oauthService.initCodeFlow('PASSWORD_RESET');
    } else {
      // Another error has occurred, e.g. the user cancelled the reset-password flow.
      // In that case, simply retry the login.
      this.oauthService.initCodeFlow();
    }
  });

  private userHasEnteredPasswordResetFlow(): boolean {
    return window.location.search.indexOf('PASSWORD_RESET') > -1;
  }

  private userHasRequestedPasswordReset(err: OAuthErrorEvent): boolean {
    return (err.params['error_description'] as string).startsWith(
      'AADB2C90118'
    );
  }

You can find a fully working example app here (just update the config): https://github.com/yuriburger/ng-azureb2c-pkce-demo

Thanks Daan Stolp for working with me on the Azure tweaks!

/Y.

More info:

You will find the code here: https://github.com/yuriburger/ng-azureb2c-pkce-demo
User Flows: https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview
The angular-oauth2-oidc library: https://manfredsteyer.github.io/angular-oauth2-oidc/docs
The RfC: https://tools.ietf.org/html/rfc7636
The news on the Implicit flow: https://oauth.net/2/grant-types/implicit

A Better RSS for Hugo

Yuri Burger — Fri, 21 Aug 2020 11:26:38 +0000

Hugo. Best static blogging platform. See my other post about migrating to Hugo.

Missing content

Hugo ships with a default RSS 2.0 template for basic feed functionality. For most feed readers this is probably ok, but for Syndication not so much. The thing is, that the feed XML only contains the basic fields, like link, title, date, description, etc. But what is missing, is the posts content.

A better template

To create a better RSS template, we start with creating a rss.xml file in layouts/_default. You could use other locations and filenames, please see the Hugo documentation for more info on this. The default template is a good starting point, so make sure you copy that content into the rss.xml file first. You can find the default file here: https://gohugo.io/templates/rss/#the-embedded-rssxml

Now we can add our article content to the RSS items by adding a "content" tag (also notice the change to the "description" tag to allow for formatted summaries):

.....
    <item>
      <title>{{ .Title }}</title>
      <link>{{ .Permalink }}</link>
      <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
      {{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
      <guid>{{ .Permalink }}</guid>

      <description>{{ "<![CDATA[" | safeHTML }} {{ .Summary }}]]></description>
      <content:encoded>{{ "<![CDATA[" | safeHTML }} {{ .Content }}]]></content:encoded>

    </item>
.....

To enable this change, the header needs to change too:

<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" 
xmlns:content="http://purl.org/rss/1.0/modules/content/" 
xmlns:atom="http://www.w3.org/2005/Atom">

W3C Validation

After these changes, you need to make sure you end up with a valid RSS feed, so let's check this with the W3C Validation Service: https://validator.w3.org/feed/:
Open your your blog RSS feed (usually located at /blog/index.xml) and paste the raw xml content in the Validation Field, press "Validate" and see if it al works out. I ended up with valid RSS but with an important recommendation:

This is of course bad for syndication, because we need an absolute URL to render the images directly from the source location.

Absolute links

So how to fix the "content:encoded should not contain relative URL references"?

I found some code on Hugo's Discourse that worked almost instantly. Thank you "hacdias" (https://discourse.gohugo.io/u/hacdias)!
Create a partial rss.html (in "layouts/partials") with the following content:

{{ $html := .Content | safeHTML }}

{{ $hrefs := findRE "href=\"([^\"]*)\"" $html }}
{{ range $href := $hrefs}}
  {{ $absHref := strings.TrimPrefix "href=\"" $href  }}
  {{ $absHref = strings.TrimSuffix "\"" $absHref  }}
  {{ $absHref = printf "href=\"%s\"" ($absHref | absURL) }}
  {{ $html = replace $html $href $absHref }}
{{ end }}

{{ $srcs := findRE "src=\"([^\"]*)\"" $html }}
{{ range $src := $srcs}}
  {{ $absSrc := strings.TrimPrefix "src=\"" $src  }}
  {{ $absSrc = strings.TrimSuffix "\"" $absSrc  }}
  {{ $absSrc = printf "src=\"%s\"" ($absSrc | absURL) }}
  {{ $html = replace $html $src $absSrc }}
{{ end }}

{{ $srcset := findRE "srcset=\"([^\"]*)\"" $html }}
{{ range $set := $srcset}}
  {{ $parts := strings.TrimPrefix "srcset=\"" $set  }}
  {{ $parts = strings.TrimSuffix "\"" $parts  }}
  {{ $parts = split $parts "," }}
  {{ $newSrcset := slice }}
  {{ range $part := $parts }}
    {{ $part = $part | replaceRE "^\\s*(.*)\\s*$" "$1" }}
    {{ $lg := split $part " " }}
    {{ $href := index $lg 0 | absURL }}
    {{ $size := index $lg 1 }}
    {{ $newSrcset = $newSrcset | append (printf "%s %s" $href $size) }}
  {{ end }}
  {{ $newSrcset = delimit $newSrcset ", " }}
  {{ $newSrcset = printf "srcset=\"%s\"" $newSrcset }}
  {{ $html = replace $html $set $newSrcset }}
{{ end }}

{{ return $html }}

And make sure we call the partial when rendering our feed XML:

<content:encoded>{{ "<![CDATA[" | safeHTML }} {{ partial "rss.html" . | safeHTML }}]]></content:encoded>

Another option is providing a "xml:base" URI and set it to the base URL of the site. Although not officially supported by W3C RSS 2.0, many readers and aggregators (reportedly) support it.

<?xml version="1.0"?>
  <rss version="2.0" xml:base="http://example.com/sub">
    <channel>
    .....

/Y.

Tips for keeping Azure Kubernetes Service costs down

Yuri Burger — Thu, 20 Aug 2020 14:48:04 +0000

Kubernetes is awesome, but can be a costly service to run. In many cases it pays off to take a look at the various components and settings to see if there are ways to save money.

How much can I save?

The amount of money you can save depends on a lot of things: type of environment (staging, production), workload, application architecture, infrastructure design, etc. But before you dive into any of the tips, you will need to start with a baseline and document at least a couple of things:

Last months bill
Current billing period forecast
Size of the Kubernetes cluster
Current/ base load of the cluster

Any Cloud Vendor has tools for cost analysis, Azure has Cost Management and Billing providing accumulated reports and breakdowns by resource. This way you can get some insight in the total costs of your Kubernetes applications. You can use filters to include all resources related to your AKS cluster (any container registries, storage accounts, Log Analytics, dependent services like KeyVault, etc.).

Make sure you have some cool reports ready to show off the fruits of your cost saving labor :).

Tips

Virtual Machines are the foundation the Azure Kubernetes Service runs on. Every AKS cluster node is a virtual machine in a "behind-the-scenes" scale set. And you get billed for every single one of them. If it is running that is. So the first three tips relate to the Virtual Machine Scale Set.

Tip #1: Scale down

Maybe you won't need the full power of the application 24/7? In that case, you can scale down or even completely shut down the Virtual Machine scaleset outside of operating hours. If you don't scale down completely, you will need to make sure you scale down the Kubernetes resources too. Otherwise Kubernetes will try to keep all the parts running on fewer nodes and you will most likely be flouded with Out Of Memory and deployment errors.

Tip within a tip: instead of manually stopping a VM Scale Set, use Azure Automation or a (scheduled) Azure Function to automate this.

More info: https://docs.microsoft.com/en-us/azure/automation/automation-solution-vm-management

Tip #2: Reserved Savings

Reserved Savings are available for certain VM series, so if you are going to run a cluster for a year or longer this could save a lot! You can check the Azure Calculator and see if reserved savings are applicable: https://azure.microsoft.com/en-us/pricing/calculator

Tip #3: Mix 'n Match

Maybe you don't need premium disks or compute optimized machines? Or specific GPU optimized nodes for certain Kubernetes applications or services but not all of them? In that case, multiple nodepools allow you to mix and match different VM types. Kubernetes "taints" and "tolerations" allow you to schedule the correct workload on the correct nodes.

More info: https://docs.microsoft.com/en-us/azure/aks/use-multiple-node-pools

Tip #4: Logging

In many cases Kubernetes apps are based on distributed architectures and logging is done somewhere central. Maybe using Application Insights or a 3rd party solution. But handling large volumes of log entries requires substantial infrastructure and can become quite expensive. I have seen cases where the cost of distributed logging almost equals the cost of running the software!

So make sure every loglevel is configurable (runtime), so you can silence most of the noise during normal operation. When troubleshooting, levels can be cranked up for short periods of time to enable all the detail needed. Also, log entries should be useful and meaningful. In distributed scenarios this means that you need to be able to correlate entries to allow for real event tracing.

Tip #5: Memory usage

Usually Kubernetes applications are cloud (native) applications. Maybe even full microservices. Yes, containers are more lightweight than VMs (they share the OS), but making sure applications run memory optimized is still very important and requires careful planning and tuning. In case of Kubernetes:

Pick a Kubernetes optimized container image based on a container friendly OS;
Define resource requests and limits for your Kubernetes deployments. If you don't do this, Kubernetes has no way to schedule them efficiently;
If you run .NET Core, make sure you build the image using the SDK image, but run the application using the Runtime image (multi stage Docker build FTW);
If you run Java, make sure you configure the JVM or try a container optimized JVM like OpenJ9;
Or run your Java workload using a container optimized stack like Quarkus.

Migrating to Hugo

Yuri Burger — Tue, 23 Jun 2020 07:32:35 +0000

(Cover image credit: Kenneth Canning/Getty Images)

So I finally decided to do it, after thinking about it at least a dozen times: I switched from using Wordpress to Hugo for my blog. I watched most of my online friends do it too the last couple of years. And all but a few ended up with a static generated site (with Jekyll, GitHub Pages or Hugo) but were pretty excited about the results.

I also thought of all the great things a static generated site would have to offer, things like writing articles in MarkDown using my favorite editor (Visual Studio Code) and total control over the generated HTML output. The reason I hesitated was, that I thought it would be a lot of work not to mention all the great features I would be missing out on (the Wordpress plugins).

It turned out to be pretty easy to do and can now also join my friends in excitement. Static sites rock.
The only thing left for me to do is, making sure everything works as expected. And that is why sharing my migration notes on my new Hugo powered platform seems like the perfect thing to do right now.

TL;DR

Wanted to move from Wordpress to a static website. Picked Hugo and Azure Static Web Apps. Migrating content turned out easier than I thought, DNS a bit tougher. I can now use Visual Studio Code and Markdown for writing articles. Ended up with a blazingly fast website behind Cloudflare.

Pick a static website framework
Select a hosting provider
Migrate content (text and media)
Fix the links (permalinks and custom 404)
Adjust DNS
Enable Search
Configure a new content workflow
Trigger social media
Configure analytics

Static website framework

The reason for me to look beyond Wordpress for my blogging site was not because I wanted to join my friends screaming with excitement. Well not the only reason. My basic needs were:

Improved workflow: I never liked writing my articles in the browser and usually prepared them in Microsoft Word or Notepad++. To be able to work with any editor and Markdown as the underlying language seemed real nice. Content as Code!
Markdown: To be able to use it as a markup language with its plain-text formatting syntax. The reason is simply because of exit scenarios. As we will see later on, getting your own content out of a CMS can be quite challenging. Because of the minimum formatting, Markdown enables you to migrate your blog content with ease.
Speed: I have a simple blogsite, nothing special. And somedays WP was just super slow and it took seconds to load my site.
Theming: I am no CSS warrior and prefer to build on the great work of those who are.

Picking a framework can be hard, so I just evaluated a couple that seemed to fit the basic needs. My shortlist was:

There are many articles on the web comparing these frameworks so if you want to know more about the differences, I suggest checking those out. My evaluation was simple: can I get a basic site up and running in under 10 minutes. As it turns out, all of them qualify :)

In short: I went with Hugo, but mainly because of the available themes.

My next step was, getting to know the new platform. There is probably no better way than writing my first post (this one) to see if I can find my way around. But because I was also hosting my blog on wordpress.com, I also needed to look for a new provider.

Hosting

Not surprisingly hosting a static website is the most basic thing to do and every provider has support for HTML files and images. There are so many options out there, just pick one. The only thing to watch out for is how you can "upload" your content. If you only have legacy FTP, you might be missing out on all the great features other hosting options have.

I picked Azure Static Web Apps, a new and shiny (also very much in preview) service from Microsoft.

A note on Azure Static Web Apps:
There is currently no support yet for "naked" (APEX) domains. This means that https://www.yuriburger.net works out of the box, but https://yuriburger.net does not. A workaround is available for the time being, but this involves Cloudflare. See later on this article for the details on that.

Content (the most important part of course)

I had not that many blogposts to migrate, maybe 80 or so. And I choose to leave a big part of that content behind, because I considered them outdated and/or not relevant anymore. Still what was left, needed some form of automated migration. Luckily the Hugo website has some links on tools that can help you with this. As it turns out, these tools focus on exporting WP content to Markdown and can be used with other blog platforms as well.

I choose to export the WP content (articles and media) and converted the text using the exitwp-for-hugo Python script.

Next, I migrated (actually just copied) the converted files to the Hugo file structure. This was the part that I "feared" the most and it took only minutes.

More info on the WP export scripts: https://gohugo.io/tools/migrations/#wordpress

Perma links (fix all the old links)

All that "old" links pointing to the old site? Usually not a problem, because most static site frameworks have a way to generate the same permalinks. In my case, I just had to make sure my articles have the correct (original) publish date.

In Hugo, this is accomplished by adjusting the config.toml file:

[permalinks]
  blog = "/:year/:month/:day/:title/"

Boom, easy fix. Now I needed to write a custom 404 (Not Found) for the cases someone used an old link pointing to content that I left behind. In the case of static websites, it is not the framework (i.e. Hugo) that handles this, but the hosting platform. In my case, I needed to provide a custom 404.html and adding a "routes.json" to the generated output and make sure it was uploaded to my Azure Static Web App.

{
  "routes": [
  ],
  "platformErrorOverrides": [
    {
      "errorType": "NotFound",
      "serve": "/404.html"
    }
  ]
}

More info: https://gohugo.io/templates/404/)

DNS (downtime about to happen)

I also hosted my DNS at Wordpress and that needed to change for various reasons. This was actually the hardest past, because it is tough to do without downtime. I wanted to move away from WP entirely so I transferred my domain to a new Registrar.

AS I mentioned in the beginning, Azure Static Web Apps do not (yet) support "naked" (or APEX or root) domains. A fix is not that hard, but requires a little bit of DNS trickery. All written up very well, so if you are like me and just want to use Azure, check this out https://burkeholland.github.io/posts/static-app-root-domain/

As a bonus, you will end up with a Cloudflare instance in front of your website. It speeds up your already fast website!

Search (yes, static sites can have search)

Search was on my checklist, but I decided I could live without it. Most of my stuff can be found using categories and tags. Turns out, there are Hugo themes that support search. Even on a static web site and that is pretty neat! If you also picked Hugo, then check out this theme https://github.com/pacollins/hugo-future-imperfect-slim for an example.

New content workflow (GitHub Actions FTW!)

Content as Code. This also means you can store your content in Azure DevOps, Bitbucket or GitHub. I choose the latter and setting up your content publishing workflow is now as easy as configuring a build pipeline.

As it turns out, Azure Static Web Apps has an even easier option. It can configure a GitHub Action directly from the Azure Portal. It recognizes the Hugo filestructure and configures the build and release automatically. Very impressive!

More info here: https://docs.microsoft.com/en-us/azure/static-web-apps/github-actions-workflow

Trigger social media on new posts

Turns out, the only WP plugin I used was for triggering social media on new posts. And Hugo has no built in support for this (because it is a static generated website). It requires daisy-chaining a couple of (free) tools to accomplish, but someone shared the struggle for us to copy: https://dereckcurry.com/posts/automatically-tweeting-new-hugo-posts/

I decided not to use this for now, as I don't mind drafting up a tweet every now and then.

Analytics

Wordpress Analytics --> Google Analytics. Not that hard, because Google Analytics have way more detail and features so no harm in switching Google for Wordpress. The frameworks I checked all had configurable support for Google Analytics.

Thats it, at least it was for me. On the whole, it took me an evening and I think it was totally worth it.

/Y.

More info on Azure Static Web Apps (be careful, in preview):
https://docs.microsoft.com/en-us/azure/static-web-apps/custom-domain

A quick intro: Application Insights for your Angular Java stack

Yuri Burger — Tue, 17 Dec 2019 00:00:00 +0000

Finding out about performance issues and collecting metrics on the usage of your app is important. Add Application Insights to your apps and let the reports tell you what is wrong and allow you to track all kinds of dimensions.

Microsoft provides several SDK’s for this, for all types of frameworks and languages. In this post, we will look at how to set this up for a typical Java (Spring Boot) API and an Angular Single Page Application. Although you can easily monitor each component separately, we also show how to enable distributed telemetry correlation. This allows you to aggegrate frontend and backend metrics in a single query, see next section!

Correlation

A special note on correlation. From the docs:

Application Insights defines a data model for distributed telemetry correlation. To associate telemetry with a logical operation, every telemetry item has a context field called operation_Id. This identifier is shared by every telemetry item in the distributed trace. So even if you lose telemetry from a single layer, you can still associate telemetry reported by other components.

A distributed logical operation typically consists of a set of smaller operations that are requests processed by one of the components. These operations are defined by request telemetry. Every request telemetry item has its own id that identifies it uniquely and globally. And all telemetry items (such as traces and exceptions) that are associated with the request should set the operation_parentId to the value of the request id.

This means, that if you enable distributed tracing correctly, you should always be able to correlate telemetry from different sources and to navigate from a distributed logical operation to the individual operations. This is going to save us a lot of time, no more plowing through logfiles!

Our sample scenario

Our scenario is pretty straightforward: an Angular frontend application that connects to a Spring Boot REST backend application. Although we do not include any backend microservices or other complex parts, it is still considered a distributed environment. The approach we are going to use can easily be extended to more complex architectures.

So we want to send both exceptions and telemetry to Application Insights.

The app

Starting with the Angular app, we need to add the Javascript SDK. You can just follow the instructions from the GitHub guide: https://github.com/microsoft/ApplicationInsights-JS but for our sample app the instructions are:

Add the library: npm i –save @microsoft/applicationinsights-web
Add the instrumentation key from Azure Application Insights to the config file /assets/config/config.develop.json
configure the distributed tracing mode
set the cloud role tag

Since this is a Single Page App, it relies on Angular routing for the navigation. To be able to pickup the route changes, the Application Insights integration is done with the help of a service that subscribes to the routers ResolveEnd event:

private appInsights = new ApplicationInsights({
    config: {
      instrumentationKey: AppConfig.settings.instrumentation,
      distributedTracingMode: DistributedTracingModes.W3C,
      disableCorrelationHeaders: false,
      enableCorsCorrelation: true
    }
  });

constructor(private router: Router) {
    this.appInsights.loadAppInsights();

    this.appInsights.addTelemetryInitializer(envelope => {
      envelope.tags\["ai.cloud.role"\] = "app";
    });

    this.router.events
      .pipe(filter(event => event instanceof ResolveEnd))
      .subscribe((event: ResolveEnd) => {
        const activatedComponent = this.getActivatedComponent(event.state.root);
        if (activatedComponent) {
          this.trackPageView(
            \`${activatedComponent.name} ${this.getRouteTemplate(
              event.state.root
            )}\`,
            event.urlAfterRedirects
          );
          this.appInsights.flush(); // Debug -> don't wait for browser to close
        }
      });
  }

Full source code: https://github.com/yuriburger/monitoring-demo-app

A couple of notes on this:

This code subscribes to the ResolveEnd event and uses some private methods to get the activated component and path that was used to match (see this blogpost https://dev.to/azure/using-azure-application-insights-with-angular-5-7-4kej for more information)
The distributed tracing method is set to W3C. The Applications Insights team is switching from the MS specific format (AI) to the more standardized W3C Trace Context ( more info on this https://docs.microsoft.com/en-us/azure/azure-monitor/app/correlation#correlation-headers )
The Instrumentation Key is gathered from the configuration service, please see the full source code for more info on this.
Normally the App Insights data is sent to MS when the browser closes. We added the appInsights.flush() to do this on every route change.

The backend

The backend is based on a simple Sprint Boot application with a REST controller. In the dependencies we enable Application Insights with the help of a starter:

<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-spring-boot-starter</artifactId>
  <version>2.5.1</version>
</dependency>

Set the correct properties:

azure.application-insights.instrumentation-key=#{INSTRUMENTATION\_KEY}#
spring.application.name=api

#Enable W3C distributed tracing support for Java apps
azure.application-insights.web.enable-W3C=true
azure.application-insights.web.enable-W3C-backcompat-mode=false

And we enable some telemetry in one of the Controller classes:

@RestController
@CrossOrigin(origins = "\*")
@RequestMapping(path = "/info")
public class InfoController {
    @Autowired
    TelemetryClient telemetryClient;

    @GetMapping(path = "", produces = "application/json")
    public ResponseEntity<Object> getInfo() {
        telemetryClient.trackEvent("Info requested...");
        return new ResponseEntity<>("{\\"version\\": \\"1.0\\"}", HttpStatus.OK);
    }
}

Full source code: https://github.com/yuriburger/monitoring-demo-api

Notes:

Update the properties file to include the correct Instrumentation Key (/src/main/resources/application.properties)
We send some custom data to App Insights with the trackEvent, but we can add other metrics as well
We distributed tracing method is set to W3C without compatibility (see https://docs.microsoft.com/en-us/azure/azure-monitor/app/correlation#correlation-headers for more info)

The result

When we run the app and the backend, logs should accumulate in Application Insights. You need to give it a few minutes, but this should be the result:

(requests
| union dependencies
| union pageViews
| union customEvents)
| where operation\_Id == "76ee5b17521b4635b0f745f2993fa60d"
| project timestamp, itemType, name, id, operation\_ParentId, operation\_Id

If we now query on operation_Id, we should get all the info in one result:

The pageView is from the Angular app, specifically the routing event.
The dependency is from the “microsoft/applicationinsights-web” npm package, it auto-collected the outgoing XHR request.
Request is coming from the Spring Boot metrics, also auto-collected and correlated using the W3C tracing headers.
The Custom Event is from the InfoController in Spring Boot.

/Y.

Canary deployments with just Azure DevOps

Yuri Burger — Mon, 09 Dec 2019 12:48:00 +0000

Canary deployments with just Azure DevOps. Well, with Azure DevOps and Azure Kubernetes Service. But that’s it, no additional software required.

Although there are plenty 3rd party solutions out there that address canary deployments, you might just get it done using “just” Azure DevOps. And in some cases, less is actually more! But to be fair, these other solutions provide a more holistic approach when it comes to deploying cloud native apps. If you are interested in those, these are the ones I know/ worked with:

If you just want to get some control on releasing new functionality in a modern cloud-native fashion, you can read on 🙂

Canary releases allow you to expose new code to a small group within the app’s “population”. It requires you to examine the canary carefully and look for unexpected behavior. If nothing hints at the app malfunctioning, you can decide to cut-over and roll out the new code to the entire group.

The backstory on the bird

For those interested, canary releases get their name from a technique that was used in the mining industry. Miners would carry a canary in a small cage to spot for mine-gas (mostly Methane). If the bird dropped, they would evacuate in fear of explosions and “air” the mine shafts before returning to their job.

Resuscitation device for the canary

Deployment scenario

The concept is simple: expose new code to a small percentage of the users. If the new code doesn’t fail, expose all users. With deployments (and in our case docker images, pods and Kubernetes in mind) it could look something like this:

First, all users are on the “left”, then a canary is deployed:

After canary analyses, the group is switched-over:

Our app will be deployed as a docker image on a managed Kubernetes cluster. So we need an Azure Container Registry and an Azure Kubernetes Service. These components don’t require any special setup, but for the deployment of our app we need to make sure we have them in place.

Within Kubernetes we usually end up with an Ingress type of setup. In the following example, we have both an app and a backend api running behind an Ingress Controller:

This setup ensures that incoming traffic for the App and Api gets routed through Kubernetes services to the pods running the containers. The way this works is that the Ingress rules match an incoming Request URI (a.k.a. path) on a Service name and the Service selects the pods based on the labels:

If we now create two deployments, one for the stabel release and one for the canary release, we can have Azure DevOps control both from a DevOps Release Pipeline. We start with one replica on the stable track (in real life there would probably be multiple replicas) and zero replicas on the canary track. Because both deployments have the “app=api” label, both are considered valid endpoints for the api-service.

Azure DevOps Release Pipeline

The multi-stage release pipeline can now control our Kubernetes deployments. We create 2 stages: Canary and Stable.

Both stages have 2 tasks: one for setting the correct image and one for scaling the deployment. These are standard Azure DevOps Kubernetes Tasks:

Canary stage:

- task: Kubernetes@0
  displayName: 'Set Canary Image'
  inputs:
    kubernetesServiceConnection: 'wherefore-aks'
    namespace: default
    command: set
    arguments: 'image deployments/api-canary api=wherefore.azurecr.io/wherefore-art-thou-api:$(Release.Artifacts._api.BuildId) --record'

- task: Kubernetes@0
  displayName: 'Scale Canary 1'
  inputs:
    kubernetesServiceConnection: 'wherefore-aks'
    namespace: default
    command: scale
    arguments: 'deployments/api-canary --replicas=1'

As you can see, we set the correct image for our api-canary deployment (in this example the artifact build ID is used for the image tag) and scale the canary deployment (api-canary) to 1 replica.

The Stable stage is just the opposite:

- task: Kubernetes@0
  displayName: 'Set Deployment Image'
  inputs:
    kubernetesServiceConnection: 'wherefore-aks'
    namespace: default
    command: set
    arguments: 'image deployments/api-deployment api=wherefore.azurecr.io/wherefore-art-thou-api:$(Release.Artifacts._api.BuildId) --record'

- task: Kubernetes@0
  displayName: 'Scale Canary 0'
  inputs:
    kubernetesServiceConnection: 'wherefore-aks'
    namespace: default
    command: scale
    arguments: 'deployments/api-canary --replicas=0'

We set the correct image for our api-deployment and scale the canary deployment (api-canary) down to 0 replicas. One important missing piece is the pre-deployment approval for the Stable stage. If we do not enable this, the Canary deployment would be practically useless as the Release would immediately go through to the Stable stage.

If we now create a new release, things should work as expected. The release is waiting on our Stable stage pre-deployment and in Kubernetes we have two deployments for our Api: one api-deployment and one api-canary.

If we approve the deployment, the api-deployment would be upgraded with the new image and the api-canary would be scaled down again: Canary deployment with just Azure DevOps 😉

/Y.

Developing Java on Azure

Yuri Burger — Mon, 03 Dec 2018 00:00:00 +0000

Part 2! In a previous post, I discussed the options for running Java workloads on Azure. Now it is time to discover some of the choices Azure offers to our software engineers!

Developing Java applications

Sourcecode

Application consist of source code that needs to be centrally stored and managed. Azure has many options for storing sourcecode, but also for working with external repositories. Although not something very specific for Java projects, still good to know Azure supports your favourite repository flavour!

Azure DevOps Git Repos

Azure DevOps (yes, this is the new name for VSTS f.k.a. Visual Studio Online) supports Git for your projects code repositories. Upon creation of a new Azure DevOps project, you are presented with some options for configuring the included Git repo.

Integration with GitHub, Gitlabs and others

Besides its own repositories, Azure has some great support for other flavours. If you configure a build pipeline for instance, you can pick from popular choices:

MongoDB

Our favourite document based database is also available on Azure. You can of course run your own VM or docker image, but Azure also offers a MongoDB as a Service. This service is called Azure Cosmos DB and is Microsoft’s globally distributed, multi-model database service. Azure Cosmos DB provides global distribution, elastic scaling and very low latencies with very high availability. And it comes with 5 different APIs including a MongoDB API.

MySQL

The popular relational database. Again, we can run this with our own VM or docker image, but it is also available as a managed service.

Azure DevOps

Azure DevOps is Microsofts collection of developer tools, cloud services and CI/CD pipelines.

Azure Boards: Work Item Tracking
Azure Repos: the Git repos mentioned above
Azure Pipelines: build, test, deploy with CI/CD
Azure Test Plans: test tools
Azure Artifacts: package, share and ship your software

Although (again) not very specific for our Java projects, it is perfectly suitable. It supports continuous integration (CI) and continuous delivery (CD) pipelines for our Java apps in Azure out of the box.

More info: https://azure.microsoft.com/en-us/services/devops/

Jenkins

If Jenkins is your CI tool of choice, you can easily integrate it with Azure DevOps and still gain alot of benefits from the Azure tools. This way you can keep Jenkins for your CI builds and use Azure for the (continuous) deployments!

More info: https://docs.microsoft.com/en-us/azure/devops/pipelines/release/integrate-jenkins-vsts-cicd?view=vsts

Maven

Microsoft provides a Maven Plugin for the Azure App Service. It provides seamless integration into Maven projects, and makes it easier for developers to deploy to different kinds of Azure Web Apps:

More info: https://github.com/Microsoft/azure-maven-plugins/tree/develop/azure-webapp-maven-plugin

Azure Pipelines

Azure Pipelines is part of the Azure DevOps tools, but also available standalone if that is all you need. Azure Pipelines offers cloud-hosted pipelines for Linux, macOS, and Windows with 10 free parallel jobs and unlimited minutes for open source projects.

If your source code resides on GitHub, it is even easier to get started with CD/CD! If you browse the GitHub CI Marketplace, you will find a plan to integrate with Azure in just a few clicks!

More info: https://github.com/marketplace/azure-pipelines

Plugins

There are several plugins available for IntelliJ and Eclipse that can really boost your Azure workflow:

Azure Toolkit for IntelliJ provides templates and functionality that allow you to easily create, develop, test, and deploy cloud application to Azure.
Azure Toolkit for Eclipse provides the same functionality, but for the Eclipse IDE.

See https://github.com/microsoft/azure-tools-for-java for more information on how to set this up.

Azure Functions

And to end this post, a Azure Service that natively supports Java: Azure Functions. Azure Functions are an easy way to run small pieces of code, or “functions,” in the cloud (think “AWS Lambda”). Functions is a solution for processing data, integrating systems, working with the internet-of-things (IoT), and building simple APIs and microservices. You can run them through triggers or on a schedule. It includes support for many languages, including Java!

More info: https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference-java

But wait, there’s still more!

Microsoft has a lot of options for running and developing Java based workloads on Azure, but this is still not not the entire story ;). There are many, many more services that support Java in one way or another, but we will leave them for another time. In one more follow up post I will be reviewing options for operating your custom Java solutions on Azure.

/Y.

Running Java on Azure

Yuri Burger — Mon, 05 Nov 2018 00:00:00 +0000

Azure is Microsofts cloud platform. It is the home of Service Apps, Logic Apps, cloud storage, Kubernetes Service and provides the foundation for VSTS (now Azure DevOps), Office 365 and loads of other services and tools.

But not only for .NET based services and applications. Todays Microsoft provides options for Linux developers, OSX teams, Docker containers, Python code, Node.js and many more different workloads. In this article series I will explore some of the Azure services and options for Java based solutions.

Running Java applications

The best part about Azure (or any other cloud platform) is the capability for running your workloads. For many different reasons the cloud has pushed companies away from running their own datacenters and in to the cloud. So what are your options for running Java applications on Microsoft Azure?

Azure Web Apps

Officially known by its full name Azure App Service Web Apps is a service for hosting web applications, REST APIs, and mobile back ends. You can develop in your favorite language, be it .NET, .NET Core, Java, Ruby, Node.js, PHP, or Python. This platform comes in two flavours: Windows based and Linux based. You use App Service on Linux to host web apps natively on Linux for Java (currently 8.0), Spring based and Apache Tomcat applications.

There is a lot of information on this and Microsoft even created different walkthroughs for both Eclipse and IntelliJ!

Docker with Web Apps for containers

If your application runtime dependencies are not supported on the default App Service for Linux, you can also deploy/ create one using your custom built Docker image. You can pull your container images from Docker Hub or a private Azure Container Registry and Web App for Containers will deploy the containerized app with your preferred dependencies to production in seconds. The platform automatically takes care of OS patching, capacity provisioning, and load balancing. More information, try this Quickstart for Java

Azure Container Instances

Azure Container Instances offer a fast and simple way of running single containers in Azure. No virtual machine hassle, no OS to manage and no orchestration. This service is best suited for small applications. You can deploy your container using bash (CLI), the Azure portal or using PowerShell. More information, try this tutorial on creating a container for deployment.

Azure Kubernetes Service

Full blown managed hosted Kubernetes. As a hosted Kubernetes service, Azure handles critical tasks like health monitoring and maintenance for you. The Kubernetes masters are managed by Azure. You only manage and maintain the agent nodes. This option is suited for all types of applications: single node, multi node, clustered, mission critical, micro service based, auto scaling, etc. More info on the product page

Azure Market Place

A quick search on the Java based products available through the Azure Market Place reveals a lot of options for running Java on Azure:

Azure Databricks using Data Factory

Ok, this is something completely different. Azure Data Factory is Microsofts cloud solution for orchestrating data pipelines. Consider it your data ETL as a service :) Azure Databricks is Microsofts Apache Spark–based analytics service. So, lets say you have Java code compiled as a .jar for certain tasks in your data pipeline (e.g. data classification), you can deploy this using Azure Data Factory on Azure Databricks. If you are into large-scale data processing, this is a great addition to your toolset. More info: https://docs.microsoft.com/en-us/azure/azure-databricks/what-is-azure-databricks

But wait, there’s more!

Microsoft has a lot of options for running Java based workloads on Azure, but this is certainly not the entire story. In two follow up posts I will be reviewing options for developing and operating Java solutions on Azure.

/Y.