In ASP.NET applications, the Web.config file is the heart of configuration. It allows us to define application settings, connection strings, error handling, session timeouts, security rules, and even URL rewriting without touching our C# backend code.
In this blog, we’ll explore:
The concept of Web.config
Redirect usage through Web.config
Page protection and security settings
URL rewriting for clean SEO-friendly URLs
Frontend usages (single name, double name, third parameter, redirects)
And finally, we’ll go line by line through a real-world Web.config example.
What is Web.config?
A special XML file used in ASP.NET applications.
It defines configuration settings such as database connections, authentication, authorization, custom errors, and security headers.
Stored at the root of the application.
What is <customErrors> in ASP.NET?
<customErrors>is a configuration element in Web.config that controls how errors are handled and displayed in ASP.NET applications.Instead of showing raw ASP.NET/YELLOW ERROR PAGES (with stack trace), we can show friendly error pages (like
Errorpage.aspx).This improves user experience and also protects sensitive error details from hackers.
Three Ways (Modes) of Using <customErrors>
1️⃣ customErrors with Mode="Off" and Status Codes Defined
<customErrors mode="Off">
<error statusCode="400" redirect="Errorpage.aspx" />
<error statusCode="403" redirect="Errorpage.aspx" />
<error statusCode="404" redirect="Errorpage.aspx" />
<error statusCode="500" redirect="Errorpage.aspx" />
</customErrors>
Explanation
mode="Off"→ Application will display detailed ASP.NET error pages (stack trace, line numbers).But here, specific error code redirections are defined.
If you visit a page that doesn’t exist → it redirects to
Errorpage.aspx.This is generally useful in development environments, where you need to debug errors but also want some controlled redirections.
If a 404 Not Found error occurs → User is redirected to
Errorpage.aspx.If a 500 Internal Server Error occurs → Same redirection.
Purpose: Developer debugging + handling user-friendly redirects.
2️⃣ customErrors with Mode="Off" (Single Line)
<customErrors mode="Off"/>
Explanation
Application will always show detailed error messages .
No redirection is done.
Useful only in local development/testing — never recommended for production.
Purpose: Debugging only (not secure).
3️⃣ customErrors with Mode="On"
<customErrors mode="On"/>
Explanation
Application will hide detailed error messages.
Instead, it will show friendly custom error pages (like Errorpage.aspx).
Secure approach for production environments.
Purpose: Protect sensitive error details from users/hackers, show professional error pages.
Quick Comparison
| Mode Value | What Happens | Best Used In |
|---|---|---|
| Off (with mapping) | Shows detailed ASP.NET errors but allows redirection for specific status codes | Development/Debugging |
| Off (without mapping) | Shows raw errors always | Local debugging only |
| On | Shows user-friendly custom error pages (e.g., Errorpage.aspx) | Production (secure) |
Final Takeaway:
Mode=Off → Developer Mode (debugging)
Mode=On → Production Mode (secure, user-friendly)
Mode=Off with status codes → Debugging + Controlled Redirection
Securing Pages with Web.config
Code Section
<validation validateIntegratedModeConfiguration="false"/>
<httpProtocol>
<customHeaders>
<remove name="X-AspNet-Version"/>
<remove name="X-AspNetMvc-Version"/>
<remove name="X-Powered-By"/>
<add name="Body-Count" value="Ice-T"/>
<add name="Access-Control-Allow-Credentials" value="true"/>
<add name="Access-Control-Allow-Headers" value="content-type"/>
<add name="X-Content-Type-Options" value="nosniff"/>
<add name="X-XSS-Protection" value="1; mode=block"/>
<add name="Cache-Control" value="no-cache, no-store, must-revalidate"/>
<add name="X-Frame-Options" value="SAMEORIGIN"/>
<add name="X-Permitted-Cross-Domain-Policies" value="none"/>
<add name="Strict-Transport-Security" value="max-age=31536000; includeSubDomains"/>
<add name="Permissions-Policy" value="accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"/>
</customHeaders>
</httpProtocol>
Line-by-Line Explanation
1. Validation Mode
<validation validateIntegratedModeConfiguration="false"/>
Concept: Controls validation of the IIS Integrated Pipeline configuration.
Why Required: Sometimes, older Web.config settings are not compatible with IIS 7+ Integrated Pipeline mode.
Purpose: Setting
falsetells ASP.NET not to validate older settings → prevents unnecessary runtime errors.
2. Removing Headers (Information Disclosure Prevention)
<remove name="X-AspNet-Version"/>
<remove name="X-AspNetMvc-Version"/>
<remove name="X-Powered-By"/>
Concept: By default, ASP.NET/IIS sends these headers in HTTP responses.
Why required: Hackers can identify framework versions and target known vulnerabilities.
Purpose: Security through obfuscation → don’t expose technology stack details.
3. Adding Custom Headers
a) Fake Header (Obfuscation / Branding)
<add name="Body-Count" value="Ice-T"/>
Concept: Adds a custom header with an arbitrary value.
Why Required: Not mandatory, but can be used for tracking or branding.
Purpose: Demonstration/fun — here it’s
"Ice-T"(artist’s name), doesn’t affect functionality.
b) CORS Headers (Cross-Origin Resource Sharing)
<add name="Access-Control-Allow-Credentials" value="true"/>
<add name="Access-Control-Allow-Headers" value="content-type"/>
Concept: Defines rules for cross-origin requests.
Why required: If your API is called from JavaScript on another domain.
Purpose
Allow-Credentials=true→ lets cookies/auth headers be sent in cross-domain requests.Allow-Headers=content-type→ allowsContent-Typeheader in requests.
c) Content Security Headers
<add name="X-Content-Type-Options" value="nosniff"/>
Concept : Stops browsers from MIME-type sniffing.
Why Required: Prevents malicious file uploads from being misinterpreted (e.g.,
.jpgrunning as script).Purpose: Protects against content-type-based attacks.
d) XSS Protection
<add name="X-XSS-Protection" value="1; mode=block"/>
Concept: Activates the browser’s built-in XSS (Cross-Site Scripting) filter.
Why Required: Prevents malicious scripts from executing in the browser.
Purpose: Block pages if XSS is detected.
e) Cache Control
<add name="Cache-Control" value="no-cache, no-store, must-revalidate"/>
Concept : Prevents caching of sensitive content.
Why Required : Avoids storing confidential pages in browser/proxy cache.
Purpose : Ensures always fresh content, good for banking/financial apps.
f) Clickjacking Protection
<add name="X-Frame-Options" value="SAMEORIGIN"/>
Concept: Controls iframe embedding.
Why Required: Attackers can load your site inside a hidden iframe and trick users (clickjacking).
Purpose: Allows embedding only from the same domain.
g) Cross-Domain Policy
<add name="X-Permitted-Cross-Domain-Policies" value="none"/>
Concept: Restricts Adobe Flash, PDF, or other plugins from making cross-domain requests.
Why Required: Stops unauthorized access from plugins.
Purpose: Set to
nonefor strictest security.
h) Strict Transport Security (HSTS)
<add name="Strict-Transport-Security" value="max-age=31536000; includeSubDomains"/>
Concept: Forces browser to use HTTPS for all requests.
Why Required: Prevents downgrade attacks and cookie hijacking on HTTP.
Purpose: Enforces HTTPS for 1 year (
31536000 seconds).
Join the conversation! Your thoughts help the community grow.