Milan Nankov

Milan Nankov

Azure App Service - Local Debugging With Custom Authentication

Having received a lot of questions on how to debug Azure App Service authentication when working locally, I decided to put together a blog post that provides additional insight on this topic.

If you would like to learn more about implementing a custom authentication, please check out the main article - Custom Authentication with Azure Mobile Apps.

How Azure App Service Authentication Works

The authentication capabilities of Azure App Service live in the cloud. If you take a look at one of the template Mobile App / Web App projects, you will not find any controllers or methods that deals with authentication. That is because the authentication is not part of your solution - it is a separate code that gets deployed to your cloud service on Azure. 

This makes total sense since authentication is crucial part of any application and if the authentication service was part of the code that everyone deploys to Azure, it could potentially lead to security risks. Also, using this approach Microsoft can transparently update and improve the authentication service without forcing users to manually push updates.

If you would like to learn more about Azure App Service authentication, please feel free to check out those two articles: Authentication and authorization for API Apps in Azure App Service and  Authentication and authorization in Azure App Service

So if authentication logic lives in the cloud, how can we actually use it when working on our dev machines?


This is where a special middleware comes into play. If you are not familiar with the notion of middleware, you can think about it as a special service that can be plugged into the pipeline of your web solution to perform specific tasks like handling incoming HTTP requests, logging, authentication, etc.

There is a middleware called AppServiceAuthenticationMiddleware that mimics the functionality of the real authentication service. When enabled, this service will allow you to debug controllers and methods that require authentication.

AppServiceAuthenticationMiddleware is usually enabled in Startup.MobileApp.cs by calling the UseAppServiceAuthentication method of the app builder instance.

Since we want this to be enabled when working locally, we use a little trick - settings.HostName will have a value only when the code is executing in the cloud. 

The code snippet above represents only half the story. AppServiceAuthenticationMiddleware validates that requests for a given controller or method have valid authentication token - the middleware does not take part in issuing tokens - it only validates them. That is why it is very important that the token creation code also changes behavior when debugging locally. 

We have to make sure that the values of the three options - SigningKeyValidAudiences and ValidIssuers - match the values that were used when creating the tokens.

Creating Authentication Tokens When Debugging

I am going to reuse the same code that I have used in the main article to demonstrate how you could setup your custom code authentication code in order to make local debugging easy as pie.

The relevant methods are GetSiteUrl() and GetSigningKey(). These provide the values for SigningKeyValidAudiences and ValidIssuers to the token creation logic. If you have previously wondered why GetSiteUrl() and GetSigningKey() have checks for settings.HostName, it should now be apparent that those checks are in place to support local debugging. If the code is running in the cloud we return the same values that we used to enable AppServiceAuthenticationMiddleware.

Wrapping up

With all code in place you should be able to hit F5 and start debugging any controller or method that uses custom authentication.

Another thing worth mentioning is that the same approach can be used to debug any Azure App Service authentication method - Facebook, Google, etc.

You can download the source code of the entire Visual Studio project from here

Need consulting on this topic?

Yes No