How to Use Custom 401 Error Page on IIS

When you need to restrict access to your web application on IIS, any unauthorized users will see the standard 401 Error Page from IIS:

401 – Unauthorized: Access is denied due to invalid credentials. You do not have permision to view this directory or page using the credentials that you supplied.

Often times, though, you want to show your end users a custom error page with specific instructions on what to do. That is certainly a more graceful way of handling the error than just showing the standard windows 401 error page.

If you have the flexibility to setup your own web instances, you might want to try using 302 Redirect instead as it’s much simpler to setup. Otherwise, this is also a viable option, although a bit long.

Steps to Use Custom 401 Error Page in IIS

1. Create an HTML page as our custom 401 page. In this example, it will be called ITNOTA-Custom-401.htm.

   

   For simplicity, we’ll save the file in C:\Temp folder.

2. Next, launch Internet Information Services (IIS) Manager and click on your site on the left pane.

3. Click on Error Pages.

   

4. On the next screen, you will see a list of default error pages according to its Status Code. In this example, we want to select 401.

   

5. On the Edit Custom Error Page window, click on the Set… button.

   

6. Under Set Localized Custom Error Path window, type in the location where the custom 401 HTML page resides in the Directory path box. Only type in the path/folder. The file name itself should be in the Relative file path textbox, then click OK.

   

7. You should see something similar to this. Click OK again.

   

8. At this point, we’re done setting up the custom 401 error page. However, unless if you still use the default for other settings, you may run into this error:

           HTTP Error 500.19 – Internal Server Error
           Absolute physical path "c:\temp" is not allowed in system.webServer/httpErrors section in web.config file. Use relative path instead.
           

   

   If you read the error message, it points exactly at the problem in the configuration, that is in the system.webServer/httpErrors section.

9. In IIS Manager, click on the server on the left navigation pane and click on Configuration Editor

   

10. In the Configuration Editor, under Section:, click on the drop-down and select system.webServer, then httpErrors.

    

11. Click on allowAbsolutePathsWhenDelegated, then click on the Unlock Attribute if it’s locked. If it’s already unlocked (no padlock sign), then you’re good. Then click Apply under Actions.

    

12. Now, click on your site on the left pane of navigation, and also click on Configuration Editor.

    

13. Repeat the step to get to the system.webServer/httpErrors and set allowAbsolutePathsWhenDelegated to True. Then, click Apply.

    

14. At this point, depending on your Authentication setting, you should be able to see the custom 401 error page in your browser (if you failed to authenticate). However, if you use Windows Authentication, you might see a 401.2 error page.

            HTTP Error 401.2 - UnauthorizedYou are not authorized to view this page due to invalid authentication headers.
            

    

    Rest easy, we just need to redirect this 401.2 error to our custom 401 error page.

15. Go back to Internet Information Services (IIS) Manager and click on your site on the left
    and Error Pages on the right.

    

16. This time, we create an additional entry for 401.2 error by clicking on the Add… link under Actions on the right pane. You can duplicate the entry for 401 setup, except this time the Status code should have a value of 401.2. Click OK.

    

17. Now you should see the list in your Error Pages windows similar to this.

    

That’s all there is to it.

As a test, we can try to load the page and when prompted to type in the a credential, you can leave it blank and click the Cancel button.

If you purposely fail the authentication to access your test website, you should see your custom 401 error page is displayed in your browser now.

Yes, it’s almost like an anti-climax to see a plain custom 401 error page being displayed. I hope you can come up with a much better design than my example to make all the effort worthwhile.

If you go to your web folder, you will see a web.config file, and your configuration is saved there:

  <httpErrors allowAbsolutePathsWhenDelegated="true">
    <remove statusCode="401" subStatusCode="-1" />
    <error statusCode="401" prefixLanguageFilePath="c:\temp" path="ITNOTA-Custom-401.htm" responseMode="File" />
    <error statusCode="401" subStatusCode="2" prefixLanguageFilePath="c:\temp" path="ITNOTA-Custom-401.htm" responseMode="File" />
  </httpErrors>
</system.webServer>

This setting for a custom 401 works for both ASP.NET and Classic ASP.

Further Reading

How to Customize 401 Error Page with 302 Redirect on IIS
How to Fix Access Denied (401) Error in Microsoft IIS
Custom 401 page in IIS with ASP.NET
Error: Vault Pre-check fails on TestASPNet.aspx – IIS shows absolute physical path is not allowed
500.19 error in IIS7 when an error occurs