IIS Support Blog articles

How to Add an Adaptive Card in Microsoft 365 Agent SDK

meenakshiBalekar — Wed, 01 Apr 2026 01:12:58 GMT

One of the most important UI capabilities is Adaptive Cards, which let your agent send structured, interactive content such as forms, inputs, buttons, and layouts.

In this guide, you’ll learn exactly how to:

Create an Agent SDK bot
Send an Adaptive Card when a user joins
Handle Action.Execute submit events
Parse user input from the card
Respond with text

I will walk through the full working code from my project.

You can download complete sample from : M365AgentSDKAdaptiveCard

Step 1: Understanding How Adaptive Cards Work in Agent SDK

Adaptive Cards are sent in the Agent SDK using:

var attachment = new Attachment { ContentType = "application/vnd.microsoft.card.adaptive", Content = <JSON> };

You then send them like this:

await turnContext.SendActivityAsync(MessageFactory.Attachment(attachment));

And to handle submit actions (Action.Execute), the Agent SDK triggers:

ActivityTypes.Invoke Name = "adaptiveCard/action"

Step 2: Use the Adaptive Card Designer

Create or test your card on our new designer here: https://adaptivecards.microsoft.com/designer

Your sample card:

Collects name & age
Uses Action.Execute with verb "personalInfo"

Step 3: The Full Working Agent SDK Code

Below is the complete working implementation showing:

✔ Welcome card using Adaptive Card
✔ Parsing Action.Execute values
✔ Responding back to the user

This is based entirely on your code, cleaned up and rewritten for clarity & correctness.

Complete Agent SDK Bot with Adaptive Card

using Microsoft.Agents.Builder; using Microsoft.Agents.Builder.App; using Microsoft.Agents.Builder.State; using Microsoft.Agents.Core.Models; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; using System.Text.Json; using System.Text.Json.Nodes; using System.Threading; using System.Threading.Tasks; namespace MyFirstAgentSDK.Bot; public class EchoBot : AgentApplication { public EchoBot(AgentApplicationOptions options, IHostEnvironment env, ILoggerFactory loggerFactory) : base(options) { OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeMessageAsync); OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last); OnActivity(ActivityTypes.Invoke, OnInvokeAsync); } private async Task WelcomeMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken) { foreach (ChannelAccount member in turnContext.Activity.MembersAdded) { if (member.Id != turnContext.Activity.Recipient.Id) { var attachment = new Attachment { ContentType = "application/vnd.microsoft.card.adaptive", Content = """ { "type": "AdaptiveCard", "version": "1.4", "schema": "http://adaptivecards.io/schemas/adaptive-card.json", "body": [ { "type": "Container", "items": [ { "type": "TextBlock", "text": "Please enter your personal information", "weight": "Bolder", "size": "Medium", "color": "Accent" }, { "type": "Input.Text", "id": "Name", "label": "What's your name?", "placeholder": "Enter your full name", "maxLength": 50, "isRequired": true, "errorMessage": "Name is required" }, { "type": "Input.Number", "id": "Age", "label": "How old are you?", "placeholder": "Enter your age", "min": 1, "max": 150, "isRequired": true, "errorMessage": "Please enter a valid age between 1 and 150" } ], "style": "emphasis", "spacing": "Medium" } ], "actions": [ { "type": "Action.Execute", "title": "Submit", "verb": "personalInfo", "style": "positive" } ] } """ }; await turnContext.SendActivityAsync(MessageFactory.Attachment(attachment), cancellationToken); } else { await turnContext.SendActivityAsync(MessageFactory.Text("Hello and Welcome!"), cancellationToken); } } } private async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken) { await turnContext.SendActivityAsync($"You said: {turnContext.Activity.Text}", cancellationToken: cancellationToken); } private async Task OnInvokeAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken) { if (turnContext.Activity.Name == "adaptiveCard/action") { JsonElement root; if (turnContext.Activity.Value is JsonElement element) { root = element; } else { var json = JsonSerializer.Serialize(turnContext.Activity.Value); root = JsonDocument.Parse(json).RootElement; } if (root.TryGetProperty("action", out var action)) { if (action.TryGetProperty("verb", out var verbElement) && verbElement.GetString() == "personalInfo") { if (action.TryGetProperty("data", out var data)) { var name = data.GetProperty("Name").GetString(); var age = data.GetProperty("Age").ToString(); await turnContext.SendActivityAsync(MessageFactory.Text($"Hello {name}, you are {age} years old!"), cancellationToken); var invokeResponse = new Activity { Type = ActivityTypes.InvokeResponse, Value = new InvokeResponse { Status = 200 } }; await turnContext.SendActivityAsync(invokeResponse, cancellationToken); } } } } } }

Step 4: What This Code Does

1. Sends an Adaptive Card when a new user joins or as per your criteria

The card that I have used includes:

Text
Name input (required)
Age input (required)
A submit button with verb "personalInfo"

2. When the user clicks Submit

Teams / Message Extension sends:

invoke name = adaptiveCard/action

OnInvokeAsync() receives:

{ "action": { "verb": "personalInfo", "data": { "Name": "...", "Age": "..." } } }

3. Bot parses and sends a text response

Example output:

Hello Meenakshi, you are 30 years old! ( P.S I am older than this )

Locally when you run the project on playground it looks like :

This is how it looks on test in webchat

And this how it looks on teams :

4. Responds with 200 status

This is required for Teams & M365:

var invokeResponse = new Activity { Type = ActivityTypes.InvokeResponse, Value = new InvokeResponse { Status = 200 } }; await turnContext.SendActivityAsync(invokeResponse, cancellationToken);

Conclusion

With the Microsoft 365 Agent SDK:

Action.Execute events are handled inside OnInvokeAsync
Inputs are parsed through the Activity.Value JSON payload
The SDK is lightweight and much simpler than the old Azure Bot SDK

Your bot is now fully capable of collecting structured user input using Adaptive Cards.

Drop in any queries or samples that you would like me to explain.

Happy Learning!

Let's Create Our First Microsoft 365 Agent SDK using Python - For Single Tenant

meenakshiBalekar — Wed, 01 Apr 2026 01:12:42 GMT

Step 1: Set Up Your Development Environment

I am using VS Code, so you don’t need to manually install Python on your system (unless you want to).
VS Code can handle Python via extensions which makes it super easy and everything at once place.

You can download complete sample : here

Install These Extensions in VS Code

Open VS Code → Extensions → install:

Python (Microsoft)
Dev Tunnels (optional but helpful)
GitHub Pull Requests & Issues ( Saves a lot of Download time)

These ensure:

You can run Python files directly inside VS Code
IntelliSense / linting works
Dev tunnel commands work in the integrated terminal

Step 2: Download/Clone the Official Sample

I am using this exact sample: Agent SDK Python Cards

Run these commands inside VS Code Terminal:

git clone https://github.com/microsoft/Agents.git cd Agents/samples/python/cards

You now have the complete working Python Agent sample.

Step 3: Install All Required Packages

Inside the cards folder, run:

pip install -r requirements.txt

This installs:

FastAPI
Uvicorn
Agents SDK
dotenv

VS Code will automatically detect and configure a Python interpreter for you. Once done, your requirements.txt file will look like :

Step 4: Add Your M365 Agent Configuration

Inside the folder, you’ll see:

.env.TEMPLATE

Rename it to:

.env

Then open the file and fill in:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID= CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET= CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=

Here I am creating a single tenant bot, hence I am suing these settings for MSI it will be different
You can refer the different type of available authentication types here

Python -m src.main

Where do these values come from?
Your Azure portal -> App Registration/ Managed Identity ( Depending on what type of application is created)

Step 5: Run the M365 Agent Locally

Start your Agent:

Python -m src.main

You will see :

But you will not be able to test the bot here locally, so we would need additional tools to help us test locally.

Step 6: Create a Dev Tunnel

You must expose your local bot over HTTPS.
For that we use devtunnel.

Step 6.1 — Authenticate devtunnel

You must authenticate first or you’ll get:

Unauthorized tunnel creation access

So run:

devtunnel user login

A browser pops up -> Sign in with the same Microsoft account used for your M365 Agent.

Step 6.2 — Create the Tunnel

Now run:

devtunnel host -p 3978 --allow-anonymous

You will get a public HTTPS URL like:

Copy this URL and we can test the bot in Azure bot service

Step 7: Update the M365 Agent Endpoint in Portal

Go to your Azure portal → ABS Agent → Settings → Endpoint URL
Paste: <tunnel-url>/api/messages

Click Save.

At this point:

Your Agent is running locally
Your tunnel is publishing it
You will be able to can talk to your Agent

Step 8: Test the Agent (The Fun Part)

Go to your Azure bot service → Test in Web Chat.

Type:

hello

You should get back the card responses from the sample.

If the sample sends Adaptive Cards or text messages, you will see them appear here exactly as coded.

That's It! You Built Your First Python M365 Agent

This guide took you from:
✔ VS Code setup
✔ Python environment extensions
✔ Cloning the sample
✔ Adding env configuration
✔ Running the Agent
✔ Creating a dev tunnel
✔ Testing in Web Chat

Happy Learning!

Resolving Weak SSL Ciphers in .NET Framework 4.5

Goyal_Sandeep — Wed, 01 Apr 2026 01:12:12 GMT

Symptom

Applications built on the .NET Framework 4.5 may fail to establish secure HTTPS connections or may default to outdated and insecure protocols. This can result in connection failures, browser security warnings, or rejection by modern APIs and services that require stronger encryption standards like TLS 1.2 or higher.

Cause

.NET framework 4.5 is out of support and hence it does not use the latest cryptography mechanisms, we strongly recommend building apps in supported frameworks. Add the support lifecycle article there

.NET Framework official support policy | .NET

Resolution

The most robust fix is to upgrade your application to .NET Framework 4.6, 4.7 or later, where TLS 1.2 is enabled by default. This ensures your application uses stronger cipher suites and secure protocols automatically, without requiring additional configuration.

After installing the newer .NET Framework on your development or production environment, update your project’s target framework and recompile. For ASP.NET applications, update your Web.config file to reflect the new framework version. For example, if upgrading to .NET 4.6:

<system.web>

</system.web>

This change, along with rebuilding your application under the updated framework, ensures that IIS and the .NET runtime use the latest libraries. Once deployed, your application will negotiate HTTPS connections using TLS 1.2 by default, resolving issues related to weak or unsupported cipher protocols.

Azure Bot Identity | Application with identifier 'x' was not found in the directory 'Bot Framework'

manojdixit — Fri, 05 Dec 2025 14:42:50 GMT

TL;DR

Every Azure Bot has a fixed identity (MicrosoftAppId) tied to either an App Registration or a Managed Identity—it cannot be changed or reused.
Azure Bot supports three identity types:
- User-Assigned Managed Identity
- Single-Tenant App Registration
- Multi-Tenant App Registration (deprecated after July 31, 2025)
Bots involve three auth flows:
1. Client → Channel (platform-specific)
2. Channel ↔ Bot (core system auth using OAuth2 + Entra ID)
3. User sign-in (optional; uses Authorization Code Flow)
The error “AADSTS700016: Application with identifier 'xxx' was not found in the directory 'Bot Framework'” happens when the Bot application tries to request tokens from the botframework.com tenant instead of its home tenant while the App registration is set as SingleTenant.
BotFrameworkAdapter Class (Microsoft.Bot.Builder) | Microsoft Learn is hardcoded to the Bot Framework tenant and does not work with Single-Tenant or Managed Identity bots. In Bot-Builder SDK (retires after Dec 2025), CloudAdapter Class (Microsoft.Bot.Builder.Integration.AspNet.Core) | Microsoft Learn supports SingleTenant and UserAssigned-MSI bots and MicrosoftAppType needs to be configured to reflect the correct Bot Identity.
With announcement of the Bot-Builder SDK deprecation, we recommend moving to The M365 Agents SDK which retains many Bot Builder concepts with ability to create next generation Agents with orchestration, observability and more secure options authentication. This also offers flexible and more secure options for token aquisition.

Skip directly to the "Channel (2) ↔ Bot (3) Authorization" section if you want to understand why the error occurs.

Azure Bot Identity

Every Azure Bot Service has a unique Id (also known as MSAAppId or MicrosoftAppId) which you can find in Azure Portal -> Azure Bot Resource -> Configuration if the Bot is created:

This MSAAppId corresponds to either the Client ID of Application Registration in Microsoft Entra ID or Managed Identity in Azure . This is Id is tied to the respective Bot Service from creation until deletion, cannot be modified or reused for a different Bot resource. Closely related to this is the concept of the Azure Bot Identity Type and can be one of the following:

User-assigned managed identity - identity tied to a Managed Identity in Azure
Single-tenant - identity tied to an Application Registration in Microsoft Entra ID with Supported account types = Accounts in this organizational directory only
- Reference - How to register an app in Microsoft Entra ID - Microsoft identity platform | Microsoft Learn
Multi-Tenant (Deprecated – ends July 31, 2025) - identity tied to an Application Registration in Microsoft Entra ID with Supported account types = Accounts in any organizational directory
- Reference - Microsoft Identity Platform Glossary - Microsoft identity platform | Microsoft Learn

References:

Create an Azure Bot resource in the Azure portal - Bot Service | Microsoft Learn

Identity and Authorization

As described in Navigating Azure Bot Networking: Key Considerations for Privatization, an Azure Bot Solution consists of below components:

Clients (1): User-facing application used to consume/converse with Bot solutions. Examples include Web Chat Widget, Teams, Slack etc.
The Bot Service: This managed SaaS umbrella includes configuration management, channel services and token services. Services are made available with the <service>.botframework.com endpoints.
The Bot Application (2): Using the Bot/Agents SDK or Composer, you create an HTTP-based application that encapsulates your functional and conversational logic, including recognition, processing, and storage. The Bot application operates using the Bot Framework Activity Specification. The Bot application exposes a public messaging endpoint for receiving activities (messaging endpoint).
Channel Connectors (3): While Azure Bot Service provides two native channels—Direct Line and Web Chat—it is designed to be highly extensible and supports integration with additional clients and communication platforms through external channels. These channels are implemented and operated by their respective providers and run within their own managed data centers. The bot’s messaging endpoint is not exposed directly to end users; instead, users interact with the bot via channel connectors, which handle session management, activity routing, and authentication on behalf of the client. Different clients, such as Teams and Slack, represent messages and activities uniquely. Since Bot applications understands and responds with activities as defined in the Bot Framework Activity Specification, channels are responsible for transforming activities and forwarding them to the application.

There are 3 Authentication/Authorization flows in a Bot solution.

Client (1) to Channel (2) Authentication - This flow is platform-specific and is implemented by the channel owner. It governs how an end-user or client application authenticates with the channel before any interaction reaches the bot. For example, the Direct Line channel requires a token or secret to establish trust, as described in Direct Line Authentication in Azure AI Bot Service - Bot Service | Microsoft Learn
Channel (2) <-> Bot (3) Authorization - This flow is channel-independent and is consistent across all Azure Bot channels. Communication between the channel and the bot occurs via bi-directional HTTPS calls secured using OAuth2 JWT Access Tokens issued by Microsoft Entra ID. Both the channel and the bot validate each other by exchanging these tokens. This mechanism is what directly relies on the Azure Bot Identity type (Managed Identity, Single-Tenant App, or legacy Multi-Tenant App) and is the primary focus of this blog.
User Authentication - This is an optional flow enables end users to authenticate within the chat experience so the bot can identify the user, access protected user data or perform actions on the user’s behalf (e.g., schedule meetings, access emails). User authentication is implemented using the "Authorization Code Flow" and supports multiple identity providers, including Microsoft Entra ID. When Entra ID is used, the bot can authenticate users using the same App Registration as the bot identity, or a separate App Registration, depending on security and design requirements. This user sign-in process is independent of the Channel-to-Bot authorization flow and is not affected by the bot’s identity type.

- References:
  - Add authentication to a bot in Bot Framework SDK - Bot Service | Microsoft Learn
  - Flow Diagram - botframework-sdk - In a brief:
    - The Bot application checks whether a user access token already exists in the Azure Bot Token Store.
    - If no token is found, the bot challenges the user to sign in within the chat interface. Some channels, such as Microsoft Teams, also support SSO - Enable SSO with Microsoft Entra ID - Teams | Microsoft Learn
    - The issued token is then securely stored in the Azure Bot Token Store.
    - The user is redirected to the configured Identity Provider (for example, Microsoft Entra ID) and authenticates successfully.
    - The Bot application retrieves the token from the Token Store and uses it to access protected resources or perform actions on the user’s behalf.

Channel (2) <-> Bot (3) Authorization

As we see in the "Outbound Flow: Bot to Channel", the Bot Application typically uses OAuth 2.0 client credentials flow on the Microsoft identity platform - Microsoft identity platform | Microsoft Learn. The token authority (endpoint) used for this flow depends on the Bot Identity Type, as documented in Authenticate requests with the Bot Connector API - Bot Service | Microsoft Learn.

The error "Application with identifier 'xxx' was not found in the directory 'Bot Framework'" happens when:

The Bot’s Application Registration is configured as Single-Tenant
(Supported account types = Accounts in this organizational directory only)
The Bot application requests a token from the Bot Framework tenant:
- https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Since the App Registration is Single-Tenant, only the home tenant can issue tokens.
The Bot Framework tenant is not the home tenant → token issuance fails.

All the operations shown in diagram except business logic is automatically handled by the SDK (BotSDK or AgentsSDK) but the Developer gets control correct token endpoint.

Bot SDK automatically infers the token endpoint/Authority based on the configuration:
- If you are using BotFrameworkAdapter Class (Microsoft.Bot.Builder) | Microsoft Learn - it will always make calls to "https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token". Thus, it cannot work with SingleTenant or UserAssigned MSI Bot.
- If you are using CloudAdapter Class (Microsoft.Bot.Builder.Integration.AspNet.Core) | Microsoft Learn, it supports configuring the Bot Identity using the MicrosoftAppType. Review samples to understand how this is configured for different runtimes:
  - BotBuilder-Samples/samples at main · microsoft/BotBuilder-Samples · GitHub
  - BotBuilder-Samples/samples/csharp_dotnetcore/02.echo-bot/appsettings.json at main · microsoft/BotBuilder-Samples · GitHub
M365 Agents SDK - This is a successor of Bot SDK and will be the only supported SDK after December 2025:
- The Identity configuration is flexible and simplified in Agents SDK. The concepts remain same, appropriate token endpoint/authority needs to be used.
  - Configure authentication in a .NET agent | Microsoft Learn
  - Agents/samples at main · microsoft/Agents · GitHub

Migration fromMultiTenant SingleTenant to in the Bot code:

With announcement of the Bot-Builder SDK deprecation, we recommend moving to Agents SDK which retains many Bot Builder concepts with ability to create next generation Agents with orchestration, observability and more secure options authentication.
- GitHub - microsoft/botframework-sdk: Bot Framework provides the most comprehensive experience for building conversation applications.
- Azure Bot Framework SDK to Microsoft 365 Agents SDK migration guidance | Microsoft Learn
For Bot SDK to work with SingleTenant, you must use CloudAdapter Class (Microsoft.Bot.Builder.Integration.AspNet.Core) | Microsoft Learn and configure correct MicrosoftAppType.

I hope it helps.

Addressing .Net EOL installations for Windows Admins

manojdixit — Fri, 28 Nov 2025 13:53:53 GMT

TL; DR:

Installing the latest .NET runtime on a server does not upgrade existing applications that are built on unsupported versions (for example, anything older than .NET 8 as of Nov 2025). Applications must be explicitly upgraded through a full development lifecycle—retargeting the project to a supported framework, updating dependencies, rebuilding, testing, and redeploying.

This is not something a Windows administrator can safely perform alone. However, admins can and should identify which applications are running on EOL .NET versions and coordinate with development teams to ensure they are upgraded to a supported release.

.NET vs .NET Framework: Understanding the Difference

Unlike the classic .NET Framework, modern .NET (formerly .NET Core) is not an integral part of the Windows operating system. It is typically installed on-demand when an application requires it. This means multiple .NET versions can coexist on the same system without automatically affecting each other.

Modern .NET is:

Cross-platform (Windows, Linux, macOS)
Open source
Designed for rapid evolution and cloud-native development

Because of these design goals, modern .NET follows a fixed annual release cadence with defined support timelines.

Official documentation:

End of Life (EOL)

As a .NET version approaches End of Life (EOL), Microsoft recommends upgrading to a supported version and reducing dependency on the expiring runtime. After EOL:

Security updates stop
Bug fixes stop
Microsoft technical support ends
Compliance and audit risks increase

Microsoft strongly discourages continued use of unsupported runtimes:

Using out-of-support .NET versions may expose your applications, data, and environment to security vulnerabilities and operational failures.

EOL is also referred to as End of Support (EOS).

Why Security Tools Flag EOL .NET Installations

Once a .NET runtime reaches EOL, vulnerability scanners and endpoint security software often flag it as a risk and recommend removal. Even if your tools do not explicitly report it, proactive removal and upgrade is still best practice.

Before uninstalling, however, administrators typically ask:

What will break if I remove this version?
Can I just install the latest .NET to replace it?
Which applications are dependent on this runtime?
Can I safely remove it if nothing appears to use it?

Here is a general workflow that can be used to address the above questions:

Step 1 – Identify Applications Using EOL ASP.NET / .NET Runtimes

Important: The steps below identify only the applications actively running at the time of execution. Any dormant services, scheduled tasks, or rarely used applications may still depend on EOL .NET but will not appear until they are executed.

To identify currently running applications that are using the .NET runtime, you can use Sysinternals ListDLLs from Microsoft.
Download ListDLLs - Sysinternals | Microsoft Learn and run the following command from an elevated (Administrator) CMD prompt:

listdlls.exe -d coreclr.dll -accepteula -vSample output of listdll command

This will show all the dotnet processes (with versions 6/7 or 8 or previous) along with version of .Net runtime loaded (coreclr). Make a note of processes that are loading EOL .Net versions - .NET and .NET Core official support policy.

Note - coreclr is the Dotnet runtime dll which will be loaded in a .Net process. The listdll shows a specific version loaded by respective process, that would help identify processes using EOL .Net runtime.

Reference - CoreCLR is now Open Source - .NET Blog

Step 2 - Reach to the developers to upgrade the Application to supported version:

Applications do not automatically upgrade to a newer .NET version simply because a supported runtime is installed on the server. Each application must be rebuilt and retargeted to explicitly use the newer framework version.
The upgrade process typically follows a full software development lifecycle (SDLC), including:
- Retargeting the project to the latest supported .NET version
- Updating NuGet packages and dependencies
- Fixing breaking changes
- Rebuilding the application
- Functional and regression testing
- Deployment to production
This process is not something a Windows administrator can safely perform alone. It requires access to the application source code and ownership from the development or product team. Administrators should focus on identifying incompatible or EOL runtimes and coordinating with application owners to plan upgrades.
Reference:
- Upgrade to a new .NET version - .NET | Microsoft Learn

Step 3 – Confirm No Applications Are Using EOL .NET Runtimes

After application owners have upgraded and deployments are completed, you must verify that no processes are still running on unsupported .NET runtimes.

Repeat the same process from Step 1 to re-scan the system:

Step 4 – Uninstall / Remove EOL .NET Runtimes

Once you confirmed no dependency on the EOL products you can proceed with uninstall.
Note that .Net apps can be self-contained or framework-dependent:
- .NET application publishing overview - .NET | Microsoft Learn
- Publish self-contained
  This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, any app dependencies, and the .NET runtime required to run the app. The environment that runs the app doesn't need to have the .NET runtime preinstalled.
- Publish framework-dependent
  This mode produces a publishing folder that includes an optional platform-specific executable used to start the app, a compiled binary containing app code, and any app dependencies. The environment that runs the app must have a version of the .NET runtime installed that the app can use.
  - Framework dependant apps will use the shared runtimes that you may have installed from Download .NET (Linux, macOS, and Windows) | .NET.
- For self-contained apps, the developer must provide a latest package with supported runtimes.
Of course, to anticipate failure, please have back up/recovery plans and execute the actions during a downtime as per your company policies.

I hope this helps.

Why Does an Old Certificate Reappear After Reboot in Azure VMs?

Shekhar — Wed, 29 Oct 2025 16:02:22 GMT

Issue Observed

A customer removed an expired SSL certificate from their Azure VM after installing a renewed one. However, after every reboot, the old certificate reappeared, and IIS site bindings automatically started picking it up.

Investigation Steps

1. Identify the Process Bringing Back the Certificate

To trace the root cause, we configured Sysmon following this guide:
Auditing Scenarios for Web Application Hosted in IIS - Part 1 - SSL Binding Modified | Microsoft Community Hub

We asked the customer to remove the certificate and reboot the server to reproduce the issue.
After rebooting, the certificate was reinstalled. Event logs revealed a process named akvvm_service.exe was responsible for bringing the certificate back.

Following is the screenshot from the event log:

I then checked the task manager to check about the process (7964) and see following:

2. What is akvvm_service.exe?

akvvm_service.exe is the service executable for the Azure Key Vault VM extension.
Purpose of this service:
- Monitors certificates stored in Azure Key Vault that the VM is configured to observe.
- Automatically downloads, installs, and refreshes those certificates into the Windows certificate store (e.g., LocalMachine\My) at a defined polling interval:
  - Azure Key Vault VM extension for Windows - Azure Virtual Machines | Microsoft Learn

3. Why Was This Happening?

The customer had multiple certificates in their Key Vault. The VM extension KeyVaultForWindows was pulling all configured certificates back into the server during every reboot.

To check the extensions:
Go to Azure VM -> Search for Extensions -> Select Extensions + applications:

We see all the Extensions + applications configured with the VM and here we see this extension KeyVaultForWindows configured:

Further checks revealed:

Issue was only happening in DEV, TEST and STG environment and not in PROD

DEV, TEST, and STG environments had the KeyVaultForWindows extension installed.
PROD environment did not have this extension, which explained why the issue was isolated to non-PROD environments.

Resolution

We shared the following action plan:

Option 1: Uninstall the Key Vault VM extension to match the PROD setup.
Option 2: Delete or disable certificates that are no longer required in Key Vault.

The customer chose Option 2 and confirmed:

“Disabling expired certificates within Key Vault fixed the issue.”

Key Takeaways

If old certificates reappear after reboot, check for Azure Key Vault VM extension.
This extension automatically syncs certificates from Key Vault to your VM.
To prevent unwanted certificates:
- Remove the extension if not needed.
- Or disable/delete unnecessary certificates in Key Vault.

Troubleshooting File Upload Error: 413 Request Body Too Large in .NET Core

Goyal_Sandeep — Tue, 02 Sep 2025 16:25:30 GMT

Troubleshooting File Upload Error: 413 Request Body Too Large in .NET Core

When working with file uploads in .NET Core, you might encounter the 413 "Request Body Too Large" error even if the maxAllowedContentLength value in your web.config file is correctly set. This issue can be perplexing, especially when all configurations seem to be in place. In this blog, we will explore a common cause of this error related to the ASPNETCORE_TEMP environment variable and how to resolve it.

Understanding the Issue

The 413 error indicates that the request body size exceeds the server's configured limit. Typically, this is controlled by the maxAllowedContentLength setting in the web.config file. However, if the ASPNETCORE_TEMP environment variable is incorrectly set, it can lead to this error despite having the correct maxAllowedContentLength value.

Scenario

Let's consider a scenario where the maxAllowedContentLength in the web.config file is set to 50 MB, but the application still throws a 413 error for files larger than 10 MB. Upon investigation, it is found that the ASPNETCORE_TEMP environment variable is incorrectly configured in the launchSettings.json file.

Steps to Resolve the Issue

Verify maxAllowedContentLength in web.config: Ensure that the maxAllowedContentLength value in your web.config file is correctly set according to your requirements. For example:

<system.webServer>

</requestFiltering>

</security>

</system.webServer>

Check ASPNETCORE_TEMP Environment Variable: The ASPNETCORE_TEMP environment variable specifies the location where ASP.NET Core stores temporary files, such as those used for buffering large request bodies. If this variable is incorrectly set, it can cause the 413 error.
Update launchSettings.json: Ensure that the ASPNETCORE_TEMP environment variable is correctly configured in the launchSettings.json file. Here is an example of how to set it:

{

"profiles": {

"IIS Express": {

"commandName": "IISExpress",

"launchBrowser": true,

"environmentVariables": {

"ASPNETCORE_ENVIRONMENT": "Development",

"ASPNETCORE_TEMP": "C:\\Temp\\ASPNETCORE"

}

"YourProjectName": {

"commandName": "Project",

"dotnetRunMessages": true,

"launchBrowser": true,

"applicationUrl": "https://localhost:5001;http://localhost:5000",

"environmentVariables": {

"ASPNETCORE_ENVIRONMENT": "Development",

"ASPNETCORE_TEMP": "C:\\Temp\\ASPNETCORE"

}

Verify the Temporary Directory: Ensure that the directory specified in the ASPNETCORE_TEMP environment variable exists and has the necessary permissions for the application to write temporary files.

Example Case

In a recent support case, the maxAllowedContentLength was set to 50 MB in the web.config file, but the application was still throwing a 413 error for files larger than 10 MB. Upon checking, it was found that the ASPNETCORE_TEMP environment variable was set to an incorrect path in the launchSettings.json file. Correcting the path resolved the issue.

Conclusion

By ensuring that the ASPNETCORE_TEMP environment variable is correctly set and the maxAllowedContentLength value in the web.config file is appropriate, you can resolve the 413 "Request Body Too Large" error in your .NET Core application. Proper configuration of these settings ensures smooth handling of large file uploads without encountering size-related errors.

If you have any further questions or need additional assistance, feel free to reach out!

Enabling Client Certificate Authentication for an Application Inside Default Web Site

Goyal_Sandeep — Tue, 02 Sep 2025 16:25:14 GMT

Enabling Client Certificate Authentication for an Application Inside Default Web Site

In this blog, we will explore how to enable client certificate authentication for a specific application hosted inside the Web Site in IIS, while keeping client certificate authentication disabled at the Web Site level. This configuration is useful when you want to secure only a particular application with client certificates, without affecting the entire site.

Understanding the Scenario

Imagine you have a Web Site in IIS that hosts multiple applications. You want to enable client certificate authentication for one specific application, but not for the entire Web Site. This setup ensures that only the designated application requires client certificates for access, while the rest of the site remains accessible without this additional layer of security.

Step-by-Step Configuration

Install IIS Client Certificate Mapping Authentication:

Open Server Manager.
Click on Manage and then Add Roles and Features.
In the Add Roles and Features Wizard, click Next until you reach the Server Roles page.
Expand Web Server (IIS), then Web Server, then Security.
Select IIS Client Certificate Mapping Authentication and click Next.
Complete the wizard and click Install

Configure SSL Settings at the Application Level:

Launch IIS Manager and navigate to your Default Web Site.
Select the specific application for which you want to enable client certificate authentication.
In the Features View, double-click on SSL Settings.
Check Require SSL and Require under Client Certificates

Disable Client Certificate Authentication at the Web Site Level:

In IIS Manager, select the Default Web Site.
Go to SSL Settings.
Ensure that Require SSL and Client Certificates are not checked

Configure Client Certificate Mapping Authentication:

Select the specific application in IIS Manager.
In the Features View, select Configuration Editor under the Management section.
Navigate to system.webServer/security/authentication/iisClientCertificateMappingAuthentication.
Set the enabled field to true.
Set the oneToOneCertificateMappingsEnabled property to true.
Click on Edit Items under the oneToOneMappings property.
Add a new mapping by providing the BLOB of the client certificate

Common Mistakes and Solutions

Configuring at the Sub-Application Level:

A common mistake is configuring client certificate authentication at the sub-application level. This approach does not work as expected and should be avoided. Instead, configure it at the server and site level to ensure proper authentication

Fallback Mechanism Issue:

Ensure that all other authentication methods are disabled for the application that requires client certificate authentication. This prevents fallback mechanisms from allowing access without the correct certificate.

Conclusion

By following these steps, you can successfully enable client certificate authentication for a specific application within the Default Web Site in IIS. This configuration ensures that only the designated application requires client certificates for access, while the rest of the site remains accessible without this additional layer of security. If you encounter any issues or need further assistance, feel free to reach out.

Identifying and Blocking Python-httpx Requests

Goyal_Sandeep — Tue, 02 Sep 2025 16:24:57 GMT

Introduction

In today’s API-driven world, automated scripts—especially those using Python libraries like httpx—can pose a risk if left unchecked. While many of these scripts are legitimate, some are used for scraping, brute-force attacks, or unauthorised data access. This blog explores how to detect and block such requests using IIS features like the URL Rewrite Module and Request Filtering.

Identifying Python-httpx Requests

The first step is detection. We identified Python scripts accessing APIs by analysing IIS logs, particularly the User-Agent field. Suspicious entries like "Python httpx" indicated automated access attempts.

Blocking with URL Rewrite Module

The URL Rewrite Module in IIS allows you to create inbound rules based on request headers. Here's how to block requests from httpx:

Open IIS Manager and navigate to your site.
Open the URL Rewrite module.
Add a new Inbound Rule.
Set the condition:

Input: {HTTP_USER_AGENT}
Check if it Matches the Pattern: .*httpx.*

Set the action to Abort Request or return a custom status code like 404.

This method is flexible—you can customise the response code or redirect the request.

Blocking with Request Filtering

As an alternative, Request Filtering offers a simpler but less flexible approach:

Open Request Filtering in IIS.
Go to the HTTP Verbs or Headers tab.
Add a rule to deny requests where the User-Agent contains httpx.

When tested, this method returned a 400 status code, effectively blocking the script.

Testing the Block

Here’s a simple Python script using httpx to test your rules:

Testing Script

Create a new Python file and give it any name (for example, TestPython.py).
Copy and paste the following content into that file.

import httpx

response = httpx.get('http://localhost/test.htm')

print(response.status_code)

Testing Method

Open the Command Prompt.
Navigate to the directory where the test Python script is located.
Run the following command:

python TestPython.py

When accessed ('http://localhost/test.htm') via a browser: 200 OK
When accessed via script: 403, 404, or 400 depending on your configuration

Choosing Between Methods

Feature	URL Rewrite Module	Request Filtering
Custom Status Codes	✅ Yes	❌ No

Conclusion

Blocking automated httpx requests is essential for protecting your APIs from misuse. IIS provides robust tools to help you do this effectively. Whether you prefer the flexibility of URL Rewrite or the simplicity of Request Filtering, both methods can be tailored to your security needs.

Troubleshooting SSL Certificate Issues in Reverse Proxy

Goyal_Sandeep — Tue, 02 Sep 2025 16:24:40 GMT

Introduction

Reverse proxies are essential in modern web architectures, especially for isolating backend services and enforcing security. However, SSL certificate issues can introduce complex challenges, particularly when dealing with HTTPS-only bindings, self-signed certificates, or organisational constraints. This blog shares practical insights from real-world troubleshooting, lab simulations, and customer scenarios.

Reverse Proxy Configuration: HTTP vs HTTPS Bindings

HTTP Binding Setup

In one scenario, I configured a reverse proxy for a backend site using HTTP binding on a custom port (e.g., 82). This setup is straightforward and avoids SSL complications. The reverse proxy helps prevent direct public access to the backend server, enhancing security.

HTTPS Binding Challenges

When the backend site is configured with only HTTPS binding (e.g., port 49494), the reverse proxy must validate the SSL certificate. This introduces challenges, especially with self-signed or privately issued certificates. In such cases, clients may encounter 502.3 - Bad Gateway errors due to failed certificate validation.

Certificate Issues and Solutions

Certificate Warnings

Accessing the reverse proxy site over HTTPS often led to browser warnings due to untrusted certificates. This is common when the backend uses a self-signed certificate or one issued by a private CA.

Solution 1: Root Certificate Installation

Installing the backend server’s root certificate on the reverse proxy server resolved the warning. This approach is secure and recommended for production environments.

Solution 2: Registry Change (Temporary)

For testing or constrained environments, I used a registry key to bypass certificate validation:

[HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\IIS Extensions\\Application Request Routing\\Parameters]

"SecureConnectionIgnoreFlags"=dword:00003100

⚠️ This is a temporary workaround and should not be used in production due to security risks.

Troubleshooting Tips

Always verify the backend URL directly from the proxy server.
Use freb logs to identify SSL handshake failures.
Monitor for 502.3 errors and correlate with certificate validation logs.

Lab Setup Guide

Prerequisites

Reverse Proxy Server (Windows Server)
Backend Server (Windows Server)
Client Machine (Windows 10/11)

Backend Server

Create a website with HTTP (e.g. port 82) and HTTPS (e.g. port 49494) bindings.
Use self-signed or test certificates for HTTPS.

Reverse Proxy Server

Configure URL rewrite rules for both HTTP and HTTPS.
Test access to backend URLs from the proxy server.
Import root certificates or apply registry changes as needed.

Client Machine

Access the reverse proxy URL and validate connectivity.
Observe browser behaviour and error messages.

Conclusion

SSL certificate issues in reverse proxy setups can be complex but manageable with the right approach. Whether you're dealing with HTTP/HTTPS bindings, self-signed certificates, or organisational constraints, understanding the root cause and applying targeted solutions is key. Collaboration, testing, and documentation are your best allies.

Troubleshooting IIS Admin Service Termination: “Invalid Signature” Error

Goyal_Sandeep — Tue, 02 Sep 2025 16:23:56 GMT

🔍 Overview

If you've encountered the following error in your Windows Event Viewer:

“The IIS Admin Service service terminated with the following service-specific error: Invalid Signature”

you're likely dealing with a cryptographic issue affecting the IIS metabase. This blog post walks you through the root causes, diagnostics, and step-by-step resolutions to restore service functionality.

🧠 What Causes This Error?

This error typically appears as Event ID 7024 and is often triggered by:

Corruption or deletion of the machine key used by IIS.
Improper SSL certificate updates.
Misconfigured permissions on cryptographic folders.

The IIS Admin Service relies on a secure machine key (usually a file starting with c23) stored in:

C:\ProgramData\Microsoft\Crypto\RSA\MachineKeys

If this key is missing or invalid, IIS cannot decrypt its configuration, resulting in the “Invalid Signature” error.

🧪 Diagnostic Steps

Check Event Viewer
Look for Event ID 7024 under System logs.
Verify Machine Key Presence
Navigate to the MachineKeys folder and check for a file starting with c23.
Audit Permissions
Ensure SYSTEM and Administrators have Full Control on the MachineKeys folder.

🛠️ Resolution Steps

✅ Option 1: Restore from Backup

If you have a backup of the c23* file:

Replace the corrupted file.
Restart the IIS Admin Service.

🔄 Option 2: Reinstall IIS 6 Metabase Compatibility

If no backup is available:

Delete the corrupted c23* file.
Open Server Manager → Manage Optional Features.
Uninstall IIS 6 Metabase Compatibility.
Reboot the server.
Reinstall the feature to regenerate the machine key.

🔐 Option 3: Reset Permissions

Ensure the following permissions on C:\ProgramData\Microsoft\Crypto\RSA\MachineKeys:

SYSTEM: Full Control
Administrators: Full Control

💡 Pro Tips

Always back up the MachineKeys folder before making changes.
Consider enabling IIS Configuration Backup for future recovery.

Capture .NET Memory Dump on Linux

meenakshiBalekar — Tue, 02 Sep 2025 16:23:35 GMT

Collecting memory dumps is a crucial part of diagnosing and troubleshooting application issues on Linux machines. Microsoft suggests three primary tools for this purpose: dotnet-dump, procdump, and createdump. In this blog post, we will explore these tools, provide the commands needed to use them, and offer a summary to understand their significance better.

1. Methods to Collect Memory Dumps on Linux

dotnet-dump

The dotnet-dump tool is a part of the .NET SDK and can be used to collect and analyze dumps. It allows you to capture a dump file from a running .NET application without needing to install additional debugging tools.

https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-dump

procdump

Procdump is a versatile tool provided by Microsoft that captures dumps based on various triggers, such as high CPU usage or unhandled exceptions. Originally built for Windows, it has been ported to Linux, offering similar functionalities.

https://github.com/microsoft/ProcDump-for-Linux

createdump

The createdump utility is specifically designed for .NET Core applications. It creates core dumps that can be used for post-mortem debugging when an application crashes.

https://learn.microsoft.com/en-us/troubleshoot/developer/webapps/aspnetcore/practice-troubleshoot-linux/lab-1-3-capture-core-crash-dumps#configure-createdump-to-run-at-process-termination

2. Command for dotnet-dump

To collect a memory dump using dotnet-dump, you can execute the following command:

./dotnet-dump collect -p <ProcessID>

In case you want to collect dump on crash you can use below :

./dotnet-dump collect -p <ProcessID> -Crashreport

Here, replace with the ID of the process you want to dump.

3. Command for procdump

To capture a dump with procdump, use the command:

sudo procdump -p <PID> -n 3 - s 10

sudo procdump -C <CPU_Usage> -M <Memory_Usage> <PID> -n 3 - s 10

In this example, the tool will create a dump if the CPU usage exceeds a certain threshold over three consecutive 10-second intervals. Adjust the parameters as needed for your specific scenario.

4. Command for createdump

To generate a dump using createdump, the command is:

sudo createdump --full <PID>

Replace with the appropriate process ID.

Summary

Collecting memory dumps is essential for diagnosing application issues on Linux. Microsoft provides three recommended tools: dotnet-dump, procdump, and createdump. Each of these tools offers unique functionalities to help capture detailed information about your applications' state at the time of issues. By utilizing the respective commands for each tool, you can efficiently collect memory dumps and troubleshoot more effectively.

The commands for capturing memory dumps are straightforward:

dotnet-dump: dotnet-dump collect -p

procdump: procdump -p -s 10 -n 3

createdump: createdump --full <PID>

By following these steps, you can ensure that you have the necessary data to analyze and resolve issues efficiently. Memory dump collection is a valuable skill for any Linux system administrator or developer, and mastering these tools will significantly enhance your troubleshooting capabilities.

Customizing Temporary File Paths in ASP.NET Applications

Tanya_Dhariwal — Tue, 02 Sep 2025 16:22:53 GMT

Issue:

In ASP.NET applications, temporary files are generated during compilation and runtime. By default, these files are stored in system directory at: C:\Windows\Microsoft.NET\Framework[64]\<version>\Temporary ASP.NET Files\.

These ASP.NET temporary files include:

Compiled assemblies (DLLs) of your web pages, user controls, and other server-side code.
Cached versions of resources like Razor views (.cshtml), Web Forms (.aspx), and other dynamic content.
Intermediate files used during the build and runtime process.

This can lead to the following issues:

Running out of space on the system drive (C:)
Difficulty in managing or monitoring temp files
Performance bottlenecks on slower disks

Resolution:

You can resolve this issue by changing the location of ASP.NET temporary files using the tempDirectory attribute in web.config. This allows you to redirect ASP.NET to use a custom directory for temporary files by modifying your web.config as follows:

<system.web>
<compilation tempDirectory="E:\TemporaryASPNETFiles" />
</system.web>

Ensure the custom folder (E:\TemporaryASPNETFiles) is:

Created manually before use.
Writable by the IIS App Pool identity, e.g., IIS APPPOOL\YourAppPoolName. You can set permissions via File Explorer or using PowerShell.

After making this change:

Recycle the application pool or
Restart IIS using iisreset to apply the new configuration

Important Note:

This setting is valid for ASP.NET (System.Web) applications running on the .NET Framework. It does not apply to ASP.NET Core.

From Hello to Secure: The SSL/TLS Handshake Explained Like a Conversation

meenakshiBalekar — Tue, 02 Sep 2025 16:21:48 GMT

Hey everyone!
Welcome back to the blog — today, we’re going to break down something that powers almost every secure interaction on the internet, but sounds way more intimidating than it is: the SSL/TLS handshake.

You can read on how to setup SSL on IIS here :

Access Denied | Microsoft Community Hub

You’ve probably heard of SSL or TLS when someone talks about “HTTPS” or “secure websites.” But what’s really happening under the hood when your browser says "Secure"? Let’s find out together.

First Things First: What Is SSL/TLS?

SSL (Secure Sockets Layer) and TLS (Transport Layer Security) are cryptographic protocols. Their job is to:

Encrypt data between client and server (so no one else can read it)
Verify that the server (and optionally the client) is who it says it is
Ensure data hasn’t been tampered with during transit

SSL is the older version, and TLS is its improved, more secure successor. Nowadays, when people say “SSL,” they usually mean “TLS.”

What Is the SSL/TLS Handshake?

Before secure communication begins, the client (like your browser) and the server (like microsoft.com) go through a process to:

Agree on how to communicate securely
Authenticate each other
Exchange keys for encryption

That process is called the SSL/TLS handshake.

Think of it like this:
The browser and server meet each other at a masquerade party. Before dancing (i.e., securely exchanging data), they check IDs, agree on the music, and lock the dancefloor so no one else can sneak in.

Step-by-Step: How the SSL/TLS Handshake Works (TLS 1.2)

Let’s break it down using TLS 1.2 (most widely used, though TLS 1.3 is also common now).

1. ClientHello

The browser initiates the handshake with:

Supported TLS versions
List of supported cipher suites (ways to encrypt)
Random number (client_random)
Optional: Server name (via SNI extension)

This is the browser saying, “Hey, here are the languages I speak. Can we talk securely?”

2. ServerHello

The server responds with:

Chosen TLS version
Selected cipher suite
Its own random number (server_random)
Digital certificate (proves its identity)
Optional: ServerKeyExchange (for some cipher suites)

This is the server saying, “Sure, I’ll speak this encryption language. Here’s my ID (certificate) to prove I am who I say I am.”

3. Certificate Verification (on client side)

The client checks if:

The certificate is valid and trusted (via CA)
The hostname matches
It’s not expired or revoked

Think of it like checking if a driver's license is real and matches the person.

4. Pre-Master Secret Generation

Client generates a Pre-Master Secret (a temporary, shared value)
It encrypts this using the server’s public key (from certificate)
Sends it to the server

Only the server can decrypt this because only it has the private key.

5. Key Derivation (on both sides)

Using:

Pre-Master Secret
client_random
server_random

Both the client and the server derive the same symmetric session key, which will be used to encrypt communication.

6. Finished Messages

Client sends a “Finished” message (encrypted with the new key)
Server sends its own “Finished” message

Now both sides know the connection is secure. The handshake is complete!

From here on, your data (like passwords, credit card info, chats) is encrypted.

What Does This Look Like in a Network Trace?

Let’s peek into a real-world network trace using Microsoft Network Monitor (NetMon) or Wireshark.

TLS:TLS Rec Layer-1 HandShake: Client Hello.

TLS:TLS Rec Layer-1 HandShake: Server Hello.; TLS Rec Layer-2 HandShake: Certificate.

TLS:Continued Data: 1378 Bytes

TLS:TLS Rec Layer-1 HandShake: Client Key Exchange.; TLS Rec Layer-2 Cipher Change Spec; TLS Rec Layer-3 HandShake: Encrypted Handshake Message.

TLS:TLS Rec Layer-1 HandShake: Encrypted Handshake Message.; TLS Rec Layer-2 Cipher Change Spec; TLS Rec Layer-3 HandShake: Encrypted Handshake Message.

TLS:TLS Rec Layer-1 SSL Application Data

What’s Happening Here?

Frame 1: ClientHello

You’ll see the cipher suites listed and maybe an SNI (like www.domain.com).

Frame 2: ServerHello + Certificate

This frame includes:

Server's selected cipher suite
Digital certificate with public key

Expand the certificate section to view fields like CN (Common Name), issuer, and validity dates.

Frame 3: ClientKeyExchange

The Pre-Master Secret is sent (encrypted with the server’s public key).

Then you’ll also see ChangeCipherSpec — this says, “From now on, I’m speaking in encrypted form.”

Frame 4: Server Finished

The server also sends ChangeCipherSpec and finishes the handshake. From this point forward, application data (like your login info) is encrypted.

Final Thoughts

And there you go! That’s the SSL/TLS handshake, explained step-by-step with a peek into what it looks like on the wire.

It might seem complicated at first, but once you break it down, it's just a smart conversation between two computers deciding how to talk securely — kind of like two spies agreeing on a secret code before chatting.

Got Questions?

Drop your questions in the comments — I love digging into anything nerdy.

Until next time — stay curious and stay secure!

Why Port 87 Works in IE and Curl but Fails in Edge and Chrome: Understanding ERR_UNSAFE_PORT

Goyal_Sandeep — Tue, 02 Sep 2025 16:21:22 GMT

Overview

In enterprise environments, configuring IIS to run on non-standard ports is a common practice. However, this can lead to unexpected browser behavior. One such case involves port 87, which works seamlessly in Internet Explorer (IE) and via Curl, but fails in Microsoft Edge and Google Chrome, throwing an ERR_UNSAFE_PORT error.

This blog explores the root cause and resolution strategies for this issue.

Summary

Environment: Windows Server with Chromium-based Edge or Chrome
Application: IIS-hosted application on port 87
Symptoms:

Works fine in Internet Explorer
Works via Curl command
Fails in Edge and Chrome with ERR_UNSAFE_PORT

Root Cause Analysis

Modern browsers like Edge and Chrome are built on the Chromium engine, which includes a security feature that blocks access to certain ports deemed unsafe. These ports are reserved for legacy or sensitive protocols and are listed in Chromium’s port_util.cc file.

Port 87 is among the restricted ports, historically associated with the ttylink protocol

The full list of blocked ports includes:

1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, ...

For the complete list, refer to https://superuser.com/questions/188058/which-ports-are-considered-unsafe-by-chrome

Resolution Options

✅ Recommended Solution: Change the Port

Action: Reconfigure IIS to use a port not listed in the restricted ports array.
Reason: Chromium browsers will continue to block unsafe ports by design. There is no registry key or browser setting to override this behavior.

🧩 Alternative: Use IE Mode in Edge

Action: Enable Internet Explorer Mode in Edge using the Enterprise Mode Site List Manager.
Use Case: If changing the port is not feasible due to legacy dependencies.

Conclusion

The ERR_UNSAFE_PORT error in Edge and Chrome is not a bug but a security feature. While legacy tools like IE and Curl bypass this restriction, modern browsers enforce it strictly. The best path forward is to migrate your IIS service to a safe port or leverage IE Mode for backward compatibility.

References

https://superuser.com/questions/188058/which-ports-are-considered-unsafe-by-chrome

https://www-archive.mozilla.org/projects/netlib/portbanning#portlist

How to Set Up SSL on IIS

meenakshiBalekar — Tue, 02 Sep 2025 16:20:32 GMT

Hi All!

If you're running a website on a Windows server using IIS (Internet Information Services), and you're thinking "How do I make my site more secure?" — you're in the right place.

In this guide, I’ll walk you through setting up SSL (Secure Sockets Layer) on IIS. Whether you're doing this for a production environment or just want to learn, I’ve got you covered.

First, What is SSL and Why Should You Care?

Think of SSL as a bodyguard for your website. It encrypts communication between your users and your server — so hackers can't snoop in and grab sensitive data like passwords or credit card numbers.

Here’s how SSL (and its more modern version TLS) protects you:

Encryption: Jumbles up data so only the intended receiver can read it.
Authentication: Confirms your website is legit — not a copycat.
Integrity: Prevents data from being tampered with in transit.

With SSL, your site changes from http:// to https:// and you get that nice padlock icon in the browser.

What You’ll Need Before Getting Started

Before jumping in, here’s your SSL setup toolkit checklist:

Item	Why It’s Needed
A domain name	SSL is tied to a specific domain
An SSL certificate	Purchased from a CA or created for internal use
Windows Server with IIS	That’s where we’ll set up the SSL
Admin access	To install and manage certificates
Port 443 open in firewall	The port SSL uses to talk to browsers

Understanding the SSL/TLS Handshake (Made Easy)

Here’s how the magic happens when someone visits your HTTPS website:

Client Hello: Your browser says, "Hi server, here’s what I support!"
Server Hello: The server replies, "Hi back! Here’s my certificate and details."
Certificate Exchange: Browser checks if the certificate is valid.
Key Exchange: They agree on encryption methods and keys.
Secure Session: Boom! Now all data is encrypted.

Imagine this like a secret handshake between your browser and the server — if done right, everything that follows is in a secret code.

How to Set Up SSL on IIS – Step by Step

Let’s get our hands dirty! Here's how you actually install and configure SSL on IIS.

Step 1: Get an SSL Certificate

You have two choices:

Buy one from a trusted Certificate Authority (e.g., DigiCert, GoDaddy, Namecheap).
Generate a self-signed certificate using IIS (only for testing or internal use not for production).

To create a self-signed cert:

Open IIS Manager
Click on your server name
Go to Server Certificates > Create Self-Signed Certificate

Step 2: Install the Certificate

Let’s plug that certificate into your server:

Press Windows + R, type mmc, hit Enter.
Go to File > Add/Remove Snap-in > Choose Certificates > Select Computer Account
Navigate to Personal > Certificates
Right-click and select Import, then follow the wizard to import your SSL certificate file.

Step 3: Bind the Certificate to Your Website

Now, let’s link the cert to your actual website:

Open IIS Manager
In the left panel, expand Sites and click on your site
Click Bindings (on the right)
Click Add → Choose Type: https → Select your certificate from the list
Hit OK and then Close

Step 4: Test the Setup

Fire up your browser and go to https://yourdomain.com ( hoping your domain is already registered )

Do you see the padlock icon?
No warnings or errors?

Awesome! Your SSL is live and ready to use

Where Are SSL Certificates Stored in Windows?

You can find them in the Windows Certificate Store, accessed via MMC:

Personal > Certificates: These are certs for the local machine
Trusted Root Certification Authorities: These store certificates from trusted CAs

Troubleshooting Tips: What If Something Goes Wrong?

Even if something breaks, don’t panic. Here's where to look:

Tool/Log	What to Check For
IIS Logs	Status codes like 403 or 500
Event Viewer	SSL handshake errors under Application logs
Browser Console	Certificate mismatches or expiry issues
Certificate Store (MMC)	Expired certs, wrong bindings

Why Use SSL? The Real Benefits

Let’s recap why this effort is totally worth it:

Better Security: Encrypts user data
More Trust: Visitors know your site is safe
Higher SEO Rankings: Search engines prefers HTTPS
Compliance: Required for GDPR, HIPAA, etc.

In short, SSL is not optional anymore — it’s essential.

Conclusion: You’ve Got This!

Setting up SSL on IIS might sound technical, but once you break it down, it’s really just a series of logical steps. You’ve now learned:

What SSL is and why it’s important
What tools you need to prepare
How to install and bind the certificate
How to troubleshoot common issues

Whether you’re securing a business site or learning for personal growth, this knowledge is a big win. If you have questions or run into problems, drop them in the comments — I’m here to help!

Mutual Authentication in IIS

meenakshiBalekar — Tue, 02 Sep 2025 16:18:41 GMT

Hey Everyone!

So today, let’s chat about something super important but often misunderstood — Mutual Authentication in IIS. If you've ever heard terms like two-way SSL, client certificates, or mutual TLS and felt a little overwhelmed — don’t worry. I'm going to break it all down for you, just like I would if we were sitting across from each other and looking at a server setup together.

Before you proceed read my previous blogs Setup SSL on IIS and TLS/SSL Handshake

Ready? Let’s go!

What is Mutual Authentication?

You know how, in most secure web connections, your browser checks the server’s certificate to make sure it’s talking to the right website? That’s one-way SSL. Now imagine flipping that around — the server also wants to verify that the client (you) is who they claim to be. That’s mutual authentication — both sides validate each other before they shake hands and start talking securely.

So instead of just saying:

"You’re The website? Okay cool, here’s my data."

Now we’re saying:

"You’re The website? Okay, prove it.
I'm a valid client? Here's my certificate — you verify it too."

Mutual authentication = trust on both sides

Where Is Mutual Authentication Used?

It’s not something you’ll see every time you browse Website or order food. This is more of a high-security feature used when it really matters, like:

Banking apps or APIs
Healthcare platforms
Internal corporate tools with sensitive data
VPN connections to internal systems
Server-to-server communications (backend services)

If you’re dealing with anything highly sensitive or regulated — mutual TLS (mTLS) is your best friend.

What You’ll Need to Get Started (Before Setting It Up in IIS)

Before we dive into mutual authentication setup in IIS, let’s make sure your toolbox is ready. Here's what you absolutely need in place:

1. SSL Certificates on Both Ends

Server Certificate: This goes on your IIS server. It authenticates the server to the client.
Client Certificate(s): Each client needs its own certificate to prove its identity to the server.

Think of this like both sides showing their ID cards before entering a secure building.

2. Trusted Certificate Authority (CA)

All certificates should be issued by a trusted CA (public or internal).
If you're using self-signed certs, make sure the full trust chain is manually imported on both client and server.

If the cert isn’t trusted, the handshake breaks right there—no second chances.

3. IIS Configured with HTTPS

IIS must be up and running with HTTPS bindings properly set up.
Make sure the server cert is already installed and bound to the right site.

4. Port 443 Open

Your firewall should allow inbound and outbound traffic on port 443.
No HTTPS = No TLS = No handshake.

5. Clients That Support Certificates

Not all browsers or systems send client certificates by default.
Make sure your client device, browser, or app supports and presents certificates when requested.

Chrome and Edge usually prompt for a certificate; some browsers need extra setup.

Step-by-Step: How to Configure Mutual Authentication in IIS

Let’s walk through this like I’m helping you set it up from scratch.

Step 1: Install and Bind the Server Certificate

Open IIS Manager → Go to Server Certificates
Install the certificate (issued to your domain name)
Go to your site → Bindings → Add or Edit binding for https and choose the certificate

Step 2: Generate and Distribute Client Certificates

Create client certificates via your internal CA or a trusted 3rd-party CA
Export them securely (with private key) and import them into clients under:
- Current User > Personal > Certificates

Step 3: Configure SSL Settings in IIS

In IIS Manager, select your site
Go to SSL Settings
Check Require SSL
Under Client Certificates, choose Require

That’s the key switch — when you hit "Require", IIS won’t just accept any request — it will demand a client certificate. If the client doesn’t provide one, it’s goodbye.

Step 4: Configure Authorization (Optional but Important)

Go to IIS > Feature View > Authorization Rules
You can allow or deny based on specific certificates or mapped Windows users (via Client Certificate Mapping)

Step 5: Enable Client Certificate Mapping via IIS Config Editor

Let’s go into the config editor and turn it on.

Open IIS Manager.
Select your website.
In the Features View, double-click Configuration Editor.
In the Section dropdown at the top, navigate to:

system.webServer/security/authentication/iisClientCertificateMappingAuthentication
Set:

- enabled: True
- oneToOneCertificateMappingsEnabled: True (if using one-to-one mappings)
- manyToOneCertificateMappingsEnabled: True (if using many-to-one mappings)

6. Click Apply on the right pane.

7. Do an IIS Reset (run iisreset in CMD) to apply changes.

Choose Your Mapping Method: One-to-One vs Many-to-One

One-to-One Mapping: Precision Control

This is tight control: each client certificate is matched to one specific Windows user.

Use this when: You want specific user-level access for each certificate.

Steps to Set Up One-to-One Mapping:

Go to IIS > Client Certificate Mapping Authentication.
On the Actions pane (right), click “Edit Feature Settings…”:
- Ensure “Enable” is checked.
Click “One-to-One Mappings…” in the right pane.
In the One-to-One dialog:
- Click Add.
- Browse and select the client certificate file (usually a .cer file).
- Provide the Windows account to map this cert to.
  - Can be local (.\username) or domain (DOMAIN\username).
- Enter the password if needed.

Done! That specific certificate now logs in as that mapped user.

Many-to-One Mapping: Broad Grouping

This is looser control: match multiple client certs using rules (e.g., same issuer) to a single Windows user.

Use this when: You want to group multiple clients under a single identity, like a shared role.

Steps to Set Up Many-to-One Mapping:

In IIS Manager, select your site.
Go to IIS > Client Certificate Mapping Authentication.
Click “Many-to-One Mappings…” in the right pane.

In the Many-to-One dialog:

In the editor, click Add (adds a new mapping item).
Configure the following properties:
- enabled: True
- name: A friendly name for this rule (e.g., FinanceCertRule)
- permissions: Usually leave default (Read)
- userName: The Windows account this cert maps to (e.g., DOMAIN\financeuser)
- password: Password for the account
- rules: Click (…) to open the Rules collection

Step-by-Step Inside rules → Add a Certificate Field Match Rule

Now you’re defining what to match from the certificate.

In the rules collection editor, click Add.
Now configure the following fields:

Property	Example Value	Description
certificateField	Subject or Issuer	Which X.509 field to inspect. Common ones: Subject, Issuer, SerialNumber, SubjectAltName
certificateSubField	CN (Common Name), O, etc.	Specific sub-field. For Subject: CN, OU, O, etc.
matchCriteria	FinanceUser001	The value to compare to (e.g., subject CN)
compareCaseSensitive	True or False	Should the match be case-sensitive?

Example: Match on Subject → CN → FinanceUser001

That means if a client presents a certificate with:

Subject: CN=FinanceUser001, OU=Finance, O=ExampleCorp

then the client will be mapped to the Windows user DOMAIN\financeuser.

Click OK on the rules editor.
Click OK on the mappings editor.
Click Apply back in the Configuration Editor.

Testing the Setup

Try accessing your site from a browser with a valid client certificate. You’ll either:

Be prompted to choose a certificate (browser pops up a dialog)
Get in successfully
Or get a 403 Forbidden error if the cert isn’t valid

Let’s Open NetMon: What Does Mutual Authentication Look Like on the Wire?

Now comes the fun part — network tracing. If you want to see mutual authentication in action, here's how you do it in Microsoft Network Monitor (NetMon) or Wireshark.

Sample Mutual Auth Flow (2-Way SSL)

Here’s what you’ll see in a successful mutual authentication session:

TLS:TLS Rec Layer-1 HandShake: Client Hello.

TLS:TLS Rec Layer-1 HandShake: Server Hello.; TLS Rec Layer-2 HandShake: Certificate. TLS Rec Layer-3 HandShake: CertificateRequest.; TLS Rec Layer-4 HandShake: ServerHelloDone.

TLS:Continued Data: 1378 Bytes

TLS:TLS Rec Layer-1 HandShake: Certificate.; TLS Rec Layer-2 HandShake: Client Key Exchange.; TLS Rec Layer-3 HandShake: Certificate Verify.; TLS Rec Layer-4 Cipher Change Spec; TLS Rec Layer-5 HandShake: Encrypted Handshake Message.

TLS:TLS Rec Layer-1 HandShake: Encrypted Handshake Message.; TLS Rec Layer-2 Cipher Change Spec; TLS Rec Layer-3 HandShake: Encrypted Handshake Message.

TLS:TLS Rec Layer-1 SSL Application Data

Key Things to Notice:

Frame 2: Server Hello + Certificate Request

This is the giveaway that mutual auth is happening.
The Certificate Request from server is not present in normal one-way SSL.
It tells the client: "Hey — now you give me your certificate too."

Frame 3: Client Certificate & Verification

The client responds with its certificate
Followed by:
- Client Key Exchange (sends Pre-Master Secret)
- Certificate Verify (proves ownership of private key)
- Change Cipher Spec (switch to encrypted mode)

Frame 4: Server Finished

Server finishes handshake and both sides can now securely talk.

If Something Fails:

Check if:

Frame 2 is missing Certificate Request → server isn’t asking for client cert.
Frame 3 doesn’t have Certificate → client didn’t send it (wrong browser, cert missing, not trusted)
You get a TLS Alert packet (e.g., “bad certificate”) → cert mismatch, expired, or not mapped.

Where Are Certificates Stored?

Here’s a quick cheat sheet:

Certificate Type	Location
Server Certificate	Local Machine > Personal
Client Certificate	Current User > Personal
Trusted Root CAs	Local Machine > Trusted Root Certification Authorities

You can open them using:

run -> certmgr.msc or
Use MMC Console → Add/Remove Snap-In → Certificates

Logs to Check If It’s Not Working

Trust me, when mutual TLS fails, you’ll want all the logs. Start here:

IIS Logs:

Found at C:\inetpub\logs\LogFiles\W3SVCx
Check for status codes like 403.7 (Client certificate required)

Event Viewer:

Windows Logs → System or Application
Look for Schannel errors — they give hints like "certificate expired" or "unable to find revocation list"

Wireshark or NetMon Captures:

Browser Debug:

Open dev tools → Security tab
You’ll often see messages like “No client certificate presented” or “Invalid certificate”

Wrapping It Up

Mutual authentication in IIS is one of those things that sounds scary but is actually really straightforward when you break it down. It's like upgrading from just checking someone's ID to both of you checking each other's passports before sitting down to talk.

By:

Installing proper certificates
Configuring IIS to require client certs
Verifying handshake using NetMon
Checking logs when things go wrong

You can set up a super secure environment that ensures only trusted clients can talk to your servers.

Need Help?

Drop a question below and I’ll help help answer it for you!
Happy learning

Addressing TLS 1.3 Compatibility Issues in IIS Express on Windows 11

MattHamrick — Fri, 29 Aug 2025 22:27:47 GMT

As Windows 10 approaches its end-of-support, these issues are becoming more prevalent as this problem has always existed on Win11. This guide will help you identify the symptoms, understand the causes, and explore potential solutions to resolve these client certificate problems in IIS Express on Win11.

Note: many of the concepts will apply to both full IIS and IIS Express, on Windows 11 and Windows Server 2022 and 2025; but this post's focus is on IIS Express on workstations.

Symptom

When launching a web app in IIS Express, the error you see if you're affected by this problem depends on which build of Win11 you're on.

Windows 11 24H2 or newer (and Windows Server 2025):

IIS detailed error page showing HTTP 500.0 Internal Server Error with the error code 0x80070032 originating from the IIS Web Core module

The error code 0x80070032 translates to ERROR_NOT_SUPPORTED.

Windows 11 Before 24H2 (and Windows Server 2022):

Standard Microsoft Edge error page showing error: "ERR_CONNECTION_RESET"

The main error there is "ERR_CONNECTION_RESET" indicating the browser's connection was unexpectedly terminated via receiving a TCP RST.

Cause

Most likely at some point in the past, the applicationhost.config file used by IIS Express was manually modified to include the below lines in some form:

<location path="" overrideMode="Allow">
  <system.webServer>
    <security>
      <access sslFlags="SslNegotiateCert" />
    </security>

One common place for this file is here:

[solution directory]\.vs\[project name]\config\applicationhost.config

The critical line is #4 with the "SslNegotiateCert" option. This could also have "SslRequireCert" to experience the same issue. By default, those sslFlags are not set in the file. Those options ("SslNegotiateCert" or "SslRequireCert") tell IIS Express, at the beginning of processing a request, to check for a client certificate. Unfortunately, at this time, that will not work on Windows 11 without some kind of workaround.

The underlying cause here is the use of TLS 1.3 by default for inbound and outbound traffic on Win11, and TLS 1.3 does not support a TLS concept known as "renegotiation." This is the same problem detailed by JasonXu in this post for Windows Server 2022 with full IIS. With this post being about IIS Express, which works differently and is managed differently than full IIS, the solutions will be mostly different here. If you want more background and technical details on how this works, continue reading past the "Solution" section below. There I will also explain the differences in symptoms/errors on the different Win11 builds.

Solutions

At the time of this writing, in late August 2025, there is no quick fix in IIS Express or the VS solution/project. I am honestly not sure if there will be a fix and what it will look like if there is. For now, there are a few ways to work around this:

Disable TLS 1.3 for inbound/server sessions on the workstation. I recommend this over other workarounds since it requires no code or any changes to the app or solution/project, and only affects inbound TLS traffic (which is typically minimal on workstations). Any outbound traffic from your browsers or any other clients won't be affected. The downside is this is machine-wide. Again, this shouldn't be a problem since on a workstation there shouldn't be anything depending on inbound TLS 1.3 specifically; however, your scenario may be different.
Update the http.sys binding via netsh to negotiate a client certificate in in the initial TLS handshake. A potential problem with this, in my opinion, is since these bindings are setup during the Visual Studio installation process (I believe), updates or changes to VS might also update these bindings and reset them to a default state, undoing your changes. I honestly don't know if this would happen and I did not test it, so it may not be a problem at all. You should be able to modify just the one binding as well. Doing this requires an administrative command prompt.
Undo/Remove the client cert configuration in the aforementioned applicationhost.config and modify app code to negate the need for client certs in this particular environment. This could get complicated and messy, but it's certainly an option.

If anything changes or other solutions come up, I will update this post if possible.

Solution #1 - Disable inbound TLS 1.3

This is done via the registry. Using your method of choice (Group Policy Preferences, .reg file, PowerShell, manually, etc.), make the below changes:

HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Server
REG_DWORD "DisabledByDefault" = 1
REG_DWORD "Enabled" = 0

Note: depending on prior configurations, the entire path above may not exist. Just create any missing folders/keys.

Here are some PowerShell commands to do it (need admin):

New-Item -Path "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols" -Name "TLS 1.3" -ErrorAction SilentlyContinue

New-Item -Path "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3" -Name "Server" -ErrorAction SilentlyContinue

Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Server" -Name "DisabledByDefault" -Value 1 -Type DWord

Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Server" -Name "Enabled" -Value 0 -Type DWord

A reboot is needed for Schannel to pick the changes up.

Solution #2 - Enable Client Certificate Negotiation via Netsh

For this option you would need to identify any https:// URLs in affected projects that need to be changed. One place to see it is in Visual Studio's project properties pane:

screenshot showing a Visual Studio 2022 project properties pane with the "SSL URL" property highlighted, containing a value of "https://localhost:44339/"

Once you have the URLs to be changed, open an admin command prompt (either on its own or via the Command Prompt option if using the Terminal app) and run the below command to see the current configuration for that binding, substituting the appropriate port for the one used in your project. The below command is to view the binding shown above:

C:\>netsh http show ssl ipport=0.0.0.0:44339

SSL Certificate bindings:
-------------------------

    IP:port                      : 0.0.0.0:44339
    Certificate Hash             : 92e10294489ad41c2a773403b8bc4cd166b03dc6
    Application ID               : {214124cd-d05b-4309-9af9-9caa44b2b74a}
    Certificate Store Name       : MY
    Verify Client Certificate Revocation : Enabled
    Verify Revocation Using Cached Client Certificate Only : Disabled
    Use Revocation Freshness Time : Disabled
    Verify Revocation Using Cached URLs Only : Disabled
    Disable Authority Info Access : Disabled
    Usage Check                  : Enabled
    Revocation Freshness Time    : 0
    URL Retrieval Timeout        : 0
    Ctl Identifier               : (null)
    Ctl Store Name               : (null)
    DS Mapper Usage              : Disabled
    Negotiate Client Certificate : Disabled
    Reject Connections           : Disabled
    Disable HTTP2                : Not Set
    Disable QUIC                 : Not Set
    Disable TLS1.2               : Not Set
    Disable TLS1.3               : Not Set
    Disable OCSP Stapling        : Not Set

The "Negotiate Client Certificate" option is the one we need to change. Changing involves deleting the binding and recreating it with the property set. You will need to make note of the Certificate Hash, Application ID, and Certificate Store Name properties to be able to recreate the binding.

Delete the binding:

C:\>netsh http delete ssl ipport=0.0.0.0:44339

SSL Certificate successfully deleted

Recreate the binding with the updated setting (this is where you need to re-enter the certificate hash, application ID, and cert store name in their respective parameters, exactly as they were before):

C:\>netsh http add ssl ipport=0.0.0.0:44339 certhash=92e10294489ad41c2a773403b8bc4cd166b03dc6 appid={214124cd-d05b-4309-9af9-9caa44b2b74a} certstorename=MY clientcertnegotiation=Enable

SSL Certificate successfully added

No reboot is needed after making this change. The same change will need to be made for any binding used where IIS Express is checking for a client certificate.

Solution #3 - App Changes

I don't cover code changes here, but if you want to remove the client cert check from IIS Express, then you can delete this part of its applicationhost.config:

<access sslFlags="SslNegotiateCert" />

This "sslFlags" property can hold multiple, comma-separate values. Thus, if other values like "Ssl" are present, you can just delete the "SslNegotiateCert" and the "SslRequireCert" values if either or both are present. If both are present, both must be deleted.

At that point, you can modify the app, if needed, to not depend on client certificates for local testing. You would want to ensure to do this in a way that won't affect production traffic (i.e. if in production this app receives requests sent to https://localhost, then you shouldn't use localhost as a way to determine if it's IIS Express or not). You can do something like using an environment variable, checking the process name (IIS Express uses "iisexpress.exe", etc. Just be sure to not add this work into a hot code path so in production the code is not executed more than needed. Ideally, this would be a check during application startup so it's only done once.

Background/Extra Information

Like full IIS, IIS Express does not directly open network sockets and listen for requests from a client at the network level. Both IIS and IIS Express use the Windows HTTP Server APIs for the actual inbound HTTP legwork. We in Microsoft support typically refer to these APIs and functionality collectively as "http.sys" since that kernel driver is where this is all handled. In other words, when a client sends a request to either IIS or IIS Express, the actual server doing the listening for and acceptance of inbound connections, any TLS stuff, and the initial HTTP request parsing, is handled by http.sys in the kernel. Once all that work is done, a handle to the HTTP request is delivered to IIS/IIS Express (in user mode) for processing. "Processing" here includes the instantiation of IIS-specific data structures, calling various modules to do things, invoking the hosted application to do its own work, etc. Once the processing is complete, IIS/IIS Express calls http.sys back to send the response.

The important part is that IIS/IIS Express doesn't have much control over the parameters of the network connection or the TLS session if applicable, and IIS/IIS Express only get involved once the actual HTTP request has been received, parsed, validated, and delivered from http.sys. Thus, when IIS/IIS Express is configured to check for and/or require a client certificate, it can only make this check long after the TLS handshake was completed. Unless the client was asked on the initial TLS handshake for a certificate, they would not have sent one.

TLS 1.2 and prior versions allow a process called renegotiation to take place. This means a second handshake will take place inside the existing encrypted tunnel, and the server can then ask the client for a certificate in that second handshake. Http.sys handles all this work with Schannel in the kernel, and IIS/IIS Express is called back for further processing once it's all done. All that extra work is invisible to the hosted application and is generally seamless.

TLS 1.3 does not allow renegotiation to take place. It does have the ability to request client authentication after the handshake (called "post-handshake client authentication", RFC), but it's 1.3-specific and the majority of clients, browsers included, have not implemented support for this extension at the time of this writing (it's optional per the RFC). Thus, unless a client certificate was negotiated from the very beginning, during the TLS handshake, one cannot be asked for or sent later with most clients. That puts IIS and IIS Express in a tight spot because they reside so late in the process - they have to tell http.sys up-front, before they get involved in the specific request, that they want a client certificate since they can't get one after-the-fact.

This was fixed in full IIS in Windows Server 2025 by adding a "Negotiate Client Certificate" checkbox to the https-type of site binding. This works because an IIS https site binding is really just a higher-level representation of an http.sys SSL binding (the ones listed in netsh http show ssl that was used earlier in this post in solution #2). I like to think of bindings as specific doors into a web site. Different bindings are different doors that require different parameters for entry. So when you create a site binding, IIS under-the-hood is calling http.sys APIs to create one of its bindings as well. That new "Negotiate Client Certificate" option maps to the "clientcertnegotiation" property which configures http.sys to request a client certificate on the initial TLS handshake, thus allowing full IIS to work with TLS 1.3+client certificates. Before this fix, and currently on Windows Server 2022, options to fix were/are similar to what's in this post for IIS Express. You could manually update the http.sys binding (like solution #2). You could also select the option to "Disable TLS 1.3 over TCP" which would effectively force TLS 1.2. Or even disable TLS 1.3 inbound. So, contrary to what I wrote higher up, there is some level of control that full IIS has over the http.sys bindings, and thus the TLS session, but not much of it is exposed or configurable to server administrators.

However, with IIS Express there is even less control; in fact, there's none. The crucial difference is in how and when those http.sys bindings are created. I mentioned above that with full IIS, they are created dynamically by IIS calling into http.sys when site bindings are configured. A binding in http.sys is tied to a specific site binding in IIS. The bindings used by IIS Express are created long in advance, and not by IIS Express itself. IIS Express has no control over those bindings. When IIS Express is not running, those bindings still exist. Those http.sys bindings are not tied to anything running in IIS Express (there is an active relationship when it's actually running to ensure requests get delivered to the IIS Express process, but the binding will remain after the process exits). You could also reconfigure the project to use a different port in Visual Studio, which would change which pre-created http.sys binding IIS Express gets bound to at runtime (if doing this you would also have to apply one of the solutions to the new binding that is being used). I do think fixing this problem will be much more complicated on the IIS Express and Visual Studio product sides since the bindings aren't created at runtime.

Lastly, why are symptoms/errors different depending on the build of Win11 being run? This behavior difference is due to how http.sys reacts to the client certificate request from IIS Express (or full IIS if that's being used). The symptom difference will also be the difference between Windows Server 2022 and 2025 and up, since those are codebases that map to different Win11 builds.

On Win11 before 24H2 (and Windows Server 2022), http.sys terminates the client's connection when a client cert was asked for, when the client does not support post-handshake client authentication. Thus, when IIS/IIS Express ask for a certificate when one was not negotiated initially, the connection is terminated. I cannot say why that is the behavior that was implemented in http.sys, but that's how it is. When this happens, IIS/IIS Express is informed of the termination so it can tear its objects and such down, but it can't do anything about it.

On Win11 24H2 and above (and Windows Server 2025), http.sys now returns a "not supported" error to IIS instead of terminating the connection. This allows IIS to continue executing and send its HTTP 500 detailed error page (it can't send an error page to the user if http.sys terminates the underlying connection) with the 0x80070032 error code.

Unfortunately, neither of the above symptoms is very helpful for diagnosing the actual cause of the problem, which is one of the reasons I wrote this post. I hope it has helped!

Thanks for reading!

Script Engine Exception. A ScriptEngine threw exception 'C0000005'

Shekhar — Wed, 02 Jul 2025 06:31:24 GMT

Issue description:

You may encounter issues when using the jscript9legacy.dll (JScript 9) JavaScript engine with Classic ASP, resulting in a Script Engine Exception. Specifically, the error message:

A ScriptEngine threw exception 'C0000005' in 'IActiveScript::SetScriptState()' from 'CActiveScriptEngine::ReuseEngine()'

indicates an access violation during script state transition. This typically occurs due to compatibility limitations between Classic ASP and the newer jscript9legacy.dll engine. Despite its name, jscript9legacy.dll is not fully compatible with Classic ASP and differs from the older jscript.dll (JScript 5.8), which is more stable in Classic ASP environments

You might see following error in the Event log:

Event Xml:

<Channel>Application</Channel>

<Computer>Computer Name</Computer>

</System>

<Data>File /AuroraWeb/ENT_Automation.asp Script Engine Exception. A ScriptEngine threw exception 'C0000005' in 'IActiveScript::SetScriptState()' from 'CActiveScriptEngine::ReuseEngine()'.</Data>

</EventData>

</Event>

More about the JavaScript libraries for Classic ASP:

jscrip9legacy is a newer engine than jscrip9legacy, don’t confuse it with the word ‘legacy’ in jscrip9legacy.

jscript.dll (Jscript 5.8) = older, compatible with Classic ASP (The real legacy dll)
jscript9legacy.dll (Jscript 9) = newer, but less compatible with Classic ASP (The fake legacy dll 😊)

The "legacy" label here refers to its role in maintaining compatibility with legacy websites (not Classic ASP) within the Internet Explorer context.

In details:

jscript.dll refers to the classic JScript engine (version 5.8), which is what Classic ASP was originally built to run on. This engine supports legacy constructs and behavior expected by older scripts and COM interactions.
jscript9.dll / jscript9legacy.dll is part of the JScript9 engine, introduced with Internet Explorer 9 to modernize JavaScript support (aligning with ECMAScript 5). It is faster and more standards-compliant….but not backward-compatible with all classic JScript features.

Fix:

You have 2 ways to fix this issue:

we need to configure the system to use the legacy JScript engine (`jscript.dll`) instead of `jscript9legacy.dll` or
Disable JScriptReplacement in the Registry.

Approach 1: use the legacy JScript engine (`jscript.dll`) instead of `jscript9legacy.dll`

This involves modifying the Windows Registry to disable the JScript9 engine for the IIS worker process (`w3wp.exe`).

Here are the steps to follow:

Open the Registry Editor (regedit).
Navigate to the following key:

`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_ENABLE_JSCRIPT9_LEGACY`

Create a new DWORD (32-bit) value named `w3wp.exe`.
Set its value to `0`.
For 32-bit systems or applications, also navigate to:

`HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_ENABLE_JSCRIPT9_LEGACY`

Repeat steps 3 and 4 in this location.
After making these changes, restart IIS to apply the new settings.

Approach 2: Disable JScriptReplacement in the Registry

This involves modifying the Windows Registry to disable the JScript9 engine for the IIS worker process (`w3wp.exe`).

Here are the steps to follow:

Open the Registry Editor (regedit).
Navigate to the following key: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Internet Explorer\Main`
Create a new DWORD (32-bit) value named `JScriptReplacement`.
Set its value to `0`.
For 32-bit systems or applications, also navigate to:

`HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Policies\Microsoft\Internet Explorer\Main`

Repeat steps 3 and 4 in this location.
After making these changes, restart IIS to apply the new settings.

After the above changes, the issue must have been fixed.

Both FEATURE_ENABLE_JSCRIPT9_LEGACY and JScriptReplacement can be used to control the behavior of the JScript engine on Windows, but they differ in scope, intent, and implementation.

FEATURE_ENABLE_JSCRIPT9_LEGACY is a feature control setting that applies on a per process basis, allowing you to disable JScript9 for specific executables like w3wp.exe. In contrast, JScriptReplacement is a policy-based setting that disables JScript9 system wide, applying broadly to all processes.

I hope this helps.

Managing IIS in PowerShell 7: Fixing Get-IISAppPool & Get-IISSite Issues

DeepakParashar — Fri, 23 May 2025 16:42:08 GMT

Managing Internet Information Services (IIS) with PowerShell is a common task for system administrators and developers. Commands like Get-IISAppPool and Get-IISSite are essential for retrieving application pools and websites. However, if you're using PowerShell 7 (PowerShell Core), you might run into compatibility issues with the IISAdministration and WebAdministration modules, leading to errors like the one shown below:

In this article, we’ll explore the root cause of this issue and provide two solutions: one for PowerShell 7 using the Microsoft.Web.Administration .NET API, and another for Windows PowerShell using the native IISAdministration module.

The Problem: Compatibility Issues in PowerShell 7

The screenshot above shows a typical error when running Get-IISAppPool in PowerShell 7. The command fails with the message: "Get-IISAppPool: The term 'Get-IISAppPool' is not recognized as a name of a cmdlet, function, script file, or executable program." Additionally, importing the WebAdministration module results in a warning: "Module WebAdministration is loaded in Windows PowerShell using WinPSCompatSession remoting session; please note that all input and output of commands from this module will be deserialized objects."

Root Cause

The IISAdministration and WebAdministration modules were designed for Windows PowerShell (version 5.1) and rely on .NET Framework assemblies like Microsoft.Web.Administration. PowerShell 7, which uses .NET Core, runs these modules in a compatibility session (WinPSCompatSession), leading to deserialized objects, performance issues, and sometimes outright failures. This is why Get-IISAppPool and Get-IISSite don’t work natively in PowerShell 7.

Solution 1: PowerShell 7-Compatible Approach Using Microsoft.Web.Administration

To manage IIS in PowerShell 7 without compatibility issues, you can directly use the Microsoft.Web.Administration .NET API. This approach bypasses the need for the IISAdministration module and works seamlessly in PowerShell 7.

Prerequisites

Ensure IIS is installed on the system, as the scripts rely on the Microsoft.Web.Administration.dll file, typically located at C:\Windows\System32\inetsrv\.

Script to List Application Pools (Equivalent to Get-IISAppPool)

try {
# Load the Microsoft.Web.Administration assembly
Add-Type -Path "C:\Windows\System32\inetsrv\Microsoft.Web.Administration.dll" -ErrorAction Stop

# Create a ServerManager instance
$serverManager = New-Object Microsoft.Web.Administration.ServerManager

# Get all application pools
$appPools = $serverManager.ApplicationPools

# Display application pool names and states
if ($appPools) {
Write-Output "Application Pools found:"
foreach ($appPool in $appPools) {
Write-Output "Application Pool: $($appPool.Name), State: $($appPool.State)"
}
} else {
Write-Output "No application pools found."
}
}
catch {
Write-Error "Failed to list application pools: $_"
}

Script to List Websites (Equivalent to Get-IISSite)

try {
# Load the Microsoft.Web.Administration assembly
Add-Type -Path "C:\Windows\System32\inetsrv\Microsoft.Web.Administration.dll" -ErrorAction Stop

# Create a ServerManager instance
$serverManager = New-Object Microsoft.Web.Administration.ServerManager

# Get all websites
$sites = $serverManager.Sites

# Display website names and states
if ($sites) {
Write-Output "Websites found:"
foreach ($site in $sites) {
Write-Output "Website: $($site.Name), State: $($site.State)"
}
} else {
Write-Output "No websites found."
}
}
catch {
Write-Error "Failed to list websites: $_"
}

Solution 2: Using Windows PowerShell with IISAdministration Module

If you prefer to use the native IISAdministration module, you’ll need to switch to Windows PowerShell (version 5.1), which is fully compatible with the module.

Steps

Open Windows PowerShell as Administrator:
- From Command Prompt, run:
  %SystemRoot%\system32\WindowsPowerShell\v1.0\powershell.exe
- Verify the version:
  $PSVersionTable.PSVersion
  You should see a Major version of 5.1.
Ensure Required IIS Features Are Installed:
- Run the following to enable necessary IIS management tools:
  Dism /Online /Enable-Feature /FeatureName:IIS-WebServerManagementTools /All /NoRestart
  Dism /Online /Enable-Feature /FeatureName:IIS-ManagementScriptingTools /All /NoRestart
- Check for a pending reboot:
  if (Test-Path "HKLM:\Software\Microsoft\Windows\CurrentVersion\Component Based Servicing\RebootPending") { Write-Warning "A reboot is required. Please restart the server." }
Install and Import the IISAdministration Module:
Install-Module -Name IISAdministration -Force
Import-Module IISAdministration -Force
Run the Commands:
- List application pools:
  Get-IISAppPool
- List websites:
  Get-IISSite

Best Practices for Production Environments

Test First: Always test scripts in a staging environment before running them in production, as enabling IIS features may require a server reboot.
Backup IIS Configuration:
"C:\Windows\System32\inetsrv\appcmd.exe" add backup "PreScriptBackup"
Run as Administrator: Ensure PowerShell is running with elevated privileges, as IIS management tasks require administrative access.
Schedule Maintenance: If a reboot is needed, schedule a maintenance window to avoid downtime.

Conclusion

Managing IIS in PowerShell 7 requires a different approach due to compatibility issues with the IISAdministration and WebAdministration modules. By using the Microsoft.Web.Administration .NET API, you can achieve the same functionality as Get-IISAppPool and Get-IISSite in a PowerShell 7-compatible way. For those who prefer the native modules, switching to Windows PowerShell provides a seamless experience.