Enable users to create custom error pages for 403 and 503 service unavailable messages
Currently 503 errors (service unavailable) present a blank white page with "service unavailable" to the users which is far from professional for us. It would be far better if we could provide a custom 503 page which would include a logo etc., and some text along the lines of "We apologise for the inconvenience, we are working on it. These issues usually resolve in about five minutes. please contact support for further help if required." or something similar.... This error might be caused by Azure network issues, so away from the web app instance.
It would also be helpful if this were possible for 403s as well. However 503 is the most important.
I have raised this idea before, but it seems to have disappeared.
I am pretty surprised that we cannot do this already.
We’re closing this item with the solutions offered below in the sample through the web.config file. Our suggestion is to take further questions to the MSDN or Stack Overflow forums for any follow up needed.
Anthony Burns commented
How can you close it when there are plenty of people highlighting that the "solutions" below don't even work?
Marc Climent commented
This is by no means closed, if the application is unavailable, web.config is not even read so the solutions proposed don't work.
In our case, that we are using client certificates, if authentication fails (at ARR level) then Azure shows a 403 without event hitting our app.
Matt P. commented
One of our web applications that is hosted with an Azure App Service has a 3rd party api that is required and sometimes has planned outages for maintenance. Since our site is not usable when this api is unavailable, we would like to be able to stop the site and display a friendly message to the users that it is unavailable and when it will be back online. Currently you see the default blue screen stating the app is off or there are problems. There should be a way to achieve this similar to the IIS app_offline.htm method but without requiring modifying the filesystem to add/remove that file. Maybe allow the user to specify a file name that is served when the app service is stopped and allow that to be deployed with the site?
Bryan Lewis commented
I have the same issue as Anthony. I have added the relevant web.config lines as listed by the Azure Team and an HTML file. Still get the default blue screen when stopped.
Anthony Burns commented
Has anyone had any success getting this to work? I've tried adding the relevant section to my web.config along with a suitable html file, but when I stop the app from the portal, I still get the standard blue and white Azure "Error 403 - This web app is stopped." page.
Paul Sterling commented
In particular, almost any content than the default 503 response would be an improvement. Certainly if a user could define the content that would be great. The current:
HTTP Error 503. The service is unavailable.
Can appear "often" for Asp.Net apps that restart or have frequent deployments causing restarts.
@Trevor: This has actually been possible for quite sometime.
The sample is just a sample, the key is the sections of the Web.config which handles the Custom Errors pages:
<httpErrors errorMode="Custom" allowAbsolutePathsWhenDelegated="true">
<remove statusCode="403" />
You need to add this section in the web.config for your application. If you don't have a web.config, you will need to create (or copy) one in order to configure this for your application.
The "Deploy to Azure" button is simply a way to deploy the sample, such that you can see the results of the web.config settings that are applied as part of the application. This is not applying anything to existing resources.
Trevor Paesl commented
Azure App Service Team: Glad to see that this may now be a possibility. Thanks! Can you please give a little background on how this actually works?
I see the github repo. I know I can fork it and update my fork with my own branding. Then I see the azuredeploy.json file which has a reference to the repo's url. I can update my fork's json file with my repo instead. So assuming that's all correct, whats the magic that happens in Azure when I push the "Purchase" button in the Azure Portal after I click the "Deploy to Azure" button?
I can see that I select a resource group and regional data center in the Azure Portal. Does this script update all my web apps within that resource group (since I didn't select them explicitly)? Also, how and what are the app(s) changed? How can I see what was updated and how can I update or undo it in the future?
We have created a sample which shows how to customize the httpErrors pages. The code is available here: https://github.com/SyntaxC4-MSFT/AppService-CustomErrorPages
The example covers 403, but it could be duplicated for other error pages. One thing to note, is that we are still confirming if the Authorization/Authentication module will respect these pages. We will update the sample if there are any additional items that we need to cover to enable that scenario.
Marc Climent commented
As well, when you use Client Certificates, if the user does not provide any cert an error 403 message appears and it's not possible to explain the user what is happening and how to solve the problem.
Shyamal Parikh commented
This is a must have feature!
+1, I strongly agree with Trevor Paesl
Andy Rivera commented
Michal Grzegorzak commented
Guys it`s a must have requirement.
This is something which could be a major problem for us. As medium sized online store, should the site ever go offline we need have that page the way we want it - so we can include a phone number of place orders through that means instead!
Steve Lautenschlager commented
I strongly second the comments here.
Ryan Sealy commented
Amen to everything mentioned here. This is a Must-Have requirement for any serious enterprise-grade deployment.
It is an essential feature, 403 and 503 errors need to be customisable.
Octavian Cosma commented
Any update on this?