IIS.Administration: a REST API in front of IIS configuration

What the service actually exposes

The repository description is one line: a REST API for managing IIS. The documentation lives at the Microsoft documentation site for IIS Administration, and the code is C#.

The idea is straightforward. IIS configuration is a rich object model, and the two ways to reach it traditionally are IIS Manager, a desktop application, and the WebAdministration PowerShell module, which is a large surface of cmdlets. Neither is pleasant to drive from a deployment script, and both require a human-shaped session on the server. This service puts an HTTP endpoint in front of the same configuration, so a site can be created or a binding changed with a POST or a PATCH from any machine that can reach the port.

The API Explorer makes that concrete. The README has a section on using the APIs through it, and the workflow is: open https://localhost:55539, go to Access Keys and get an access token, then go back to API Explorer and paste the Access Token. From there the browse path for sites is https://localhost:55539/#/api/webserver/websites, and the expectation is that you see all local Web sites listed.

That URL is worth pausing on. The default port is 55539 and it is bound to localhost, which means the API Explorer is a local tool by default and the service is not reachable from another machine unless you change the binding. The C# examples in the README all target the same localhost address, which confirms the intent.

The audience is therefore Windows administrators and deployment tooling, on a machine where the service has been installed and the caller has been granted rights. The default branch is dev rather than main, which tells you the project works in a development branch rather than a release branch, and the last push to the repository was on 2026-05-26.

Tokens, groups and the two-list permission model

Access control is the part of the design that most affects whether you can use the thing, and it is a two level model.

The first level is a Windows group called IIS Administration API Owners. The README's known issues section says that if you do not have permissions for the APIs, you should add yourself to that group on the host machine, and that if you still do not have permissions after that, you should add yourself to the users/administrators and users/owners lists in appsettings.json.

The second level is the configuration file. The development instructions point at src\Microsoft.IIS.Administration\config\appsettings.json and say to modify the users section:

"users": {
      "administrators": [
        "mydomain\\myusername",
        "[email protected]",
        "IIS Administration API Owners"
      ],
      "owners": [
        "mydomain\\myusername",
        "[email protected]",
        "IIS Administration API Owners"
      ]
    },

Entries are matched as a domain qualified account, an email address, or the name of the group, and the same entries appear in both lists. The administrators list and the owners list are separate roles, and a caller in one is not automatically in the other.

The token itself is issued from the Access Keys page of the API Explorer, and the C# example shows how it travels: as an Access-Token header whose value is the literal string Bearer followed by the token.

That scheme is a simple shared secret rather than an OAuth flow, which is consistent with a service that is expected to sit behind a reverse proxy on a trusted host. The consequence for a reader is that the security of the whole thing depends on who can reach the port and on the token staying secret, and the README's own recommendation of nginx-style TLS termination in front of the service follows from that.

Creating a site over HTTP, and the file permissions that gate it

The README walks through creating a web site through the API Explorer, and the example request shows the shape of the API.

In API Explorer you click POST on the websites collection, paste a JSON request, and the body carries a name, a physical path and a list of bindings:

{
  "name": "Contoso1234",
  "physical_path": "C:\\inetpub\\wwwroot",
  "bindings": [
    {
      "port": 8080,
      "protocol": "http",
      "ip_address": "*"
    }
  ]
}

The interesting failure mode is documented right after it. If you do not have permissions to create web sites under C:\Inetpub, you need a files section in appsettings.json:

  "cors": {
    "rules": []
  },
  "files": {
    "locations": [
      {
        "alias": "inetpub",
        "path": "C:\\inetpub",
        "claims": [
          "read",
          "write"
        ]
      }
  ]

So the API does not simply write to the disk. It has a permissions model for file locations, with an alias, a path and a set of claims. A caller can create a site whose physical path is under an alias it has been granted, and a request to create one outside a granted location fails on permissions rather than on a missing feature. The cors section is a separate concern and is required alongside the files section.

The README then confirms the loop closes: click the arrow, the new web site should be created, open IIS Manager and you will see it under Sites, then click DELETE in the browser and it should be removed. That round trip through both interfaces is a useful sanity check, since it proves the service and the traditional tools are operating on the same configuration.

The C# client, HAL and the PATCH idiom

The C# examples in the README show the client pattern, and it is short enough to be worth quoting in full.

var apiClient = new HttpClient(new HttpClientHandler() {
   UseDefaultCredentials = true
}, true);

// Set access token for every request
apiClient.DefaultRequestHeaders.Add("Access-Token", "Bearer {token}");

// Request HAL (_links)
apiClient.DefaultRequestHeaders.Add("Accept", "application/hal+json");

Three things are happening there. UseDefaultCredentials means the Windows identity of the calling process is sent, so the service sees who is calling in addition to the token. The Access-Token header carries the bearer value on every request rather than per call, which is why the client is configured once. And the Accept header asks for application/hal+json, with the comment noting the request is for HAL, the _links representation.

HAL is the mechanism that makes the API navigable, and it shows up in the update example. Reading sites parses a JArray out of the response:

var res = await apiClient.GetAsync("https://localhost:55539/api/webserver/websites");

if (res.StatusCode != HttpStatusCode.OK) {
  HandleError(res);
  return;
}

JArray sites = JObject.Parse(res.Content.ReadAsStringAsync().Result).Value<JArray>("websites");

and updating a site follows the self link rather than constructing a URL, which is the whole point of a hypermedia API:

var updateRequest = new HttpRequestMessage(new HttpMethod("PATCH"),
    "https://localhost:55539" + site["_links"]["self"].Value<string>("href"));

The create example posts a new site object and checks for HttpStatusCode.Created, and the update example expects HttpStatusCode.OK. So the resource model is a conventional REST one with PATCH for partial updates, and the _links collection is what tells a client where a resource lives and what it can do with it.

A limitation worth naming for anyone writing a client: the examples read the response body synchronously with res.Content.ReadAsStringAsync().Result, which blocks the calling thread. That is fine in a console tool and wrong inside a request handler.

Installing the service, and the list of things that break

The Installation and Known Issues section is the most useful part of the README, because it is a list of real problems with real answers, and it is longer than the feature documentation.

The order of operations matters. You must first remove preview builds of .NET Core, because the service does not work with them, and you must remove previously installed versions of IIS Administration. Repair does not work, so a full uninstall and re-install is the only path.

When an installation fails, the recovery is manual and specific. Remove the folder C:\Program Files\IIS Administration and the Windows service named Microsoft IIS Administration. If that does not fix it, remove the user group IIS Administration API Owners from the host machine and run setup again.

The permission recovery follows the same order in reverse. Add yourself to the IIS Administration API Owners group, and if that is still not enough, add yourself to the users/administrators and users/owners lists in appsettings.json.

There are two smaller ones worth knowing. If you have trouble viewing the access token created from the API Explorer in Microsoft Edge, the fix is to reset the browser settings at edge://settings/reset, which tells you the issue is in Edge's handling of the page rather than in the service. And there is a version conflict to be aware of: Microsoft.Web.Administration.dll has conflicts with .NET 6.0, and the workaround is to remove all code related to ms.web.admin.refs in the future when it is ported to .NET 6.0.

The platform support is stated as 64 bit Windows Server 2008 R2 and above, and there is a separate blog post on running the service on Nano Server.

The overall picture is a service that assumes it is being installed by someone with administrative rights on a machine they control, with a fallback to manual cleanup rather than a repair path.

Building the installer and the release history

The build instructions assume Visual Studio 2022 on Windows, and the sequence is: start the developer command prompt, publish the solution, then build the installer.

%comspec% /k "C:\Program Files\Microsoft Visual Studio\2022\Preview\Common7\Tools\VsDevCmd.bat"

cd /d C:\src\repos\IIS.Administration
msbuild -restore Microsoft.IIS.Administration.sln /t:publish

build\nuget.exe restore installer\IISAdministrationSetup\packages.config -SolutionDirectory installer
msbuild installer /p:configuration=release

The README notes that the path in the first block has to be replaced to match your clone location. The output lands in installer\IISAdministrationBundle\bin\x64\Release, so the installer is a separate artefact built from the published solution rather than part of the main build.

The testing instructions follow the same shape, with a script and a configuration file. You run Configure-DevEnvironment.ps1 with the test environment flag:

   C:\src\repos\IIS.Administration\scripts\Configure-DevEnvironment.ps1 -ConfigureTestEnvironment

then open the project in Visual Studio as an Administrator and launch without debugging, using a settings file similar to test\appsettings.test.json, which must contain the files and cors sections or new web sites cannot be created. The tests need to create new local users and enable some IIS features, which is why the second instance also has to run elevated, and they can be run from the test folder or with the CLI.

The release history is where the project needs the most careful reading. The recent tags are v6.0.0 from 2022-09-27, v2.3.0 from 2019-06-10 and v2.2.1 from 2019-02-27, so the version numbering jumped from 2 to 6 and the newest published tag is more than three years old, while the last push to the repository was on 2026-05-26. The default branch is dev, and the version scheme is not the one a package manager would use.

The licence is a custom one that the hosting platform cannot categorise, with the terms in LICENSE.md at the root of the repository, and the tree carries a SECURITY.md and a ThirdPartyNotices.txt alongside the source, the installer directory, the scripts, the test suite, the build directory and an azure-pipelines directory for continuous integration. For a service that a team would run inside its own network rather than embed in a product, that licence shape is workable, and the SECURITY file is where a disclosure would go.

Editorial conclusion

Adopt IIS.Administration if you need to create and modify IIS configuration from code, particularly from a deployment pipeline that runs on a Windows server where the IIS Manager UI and the PowerShell cmdlets are both awkward to drive. Do not adopt it as a general web management console, since it is an API for configuration objects and not an operations surface, and do not adopt it on a machine you cannot administer, since installation requires elevated privileges and the README lists several manual cleanup steps after a failure. Verify first which .NET runtime is on the host, because the service does not work with preview builds and the README documents an assembly reference conflict with .NET 6, that the callers who need it are in the IIS Administration API Owners group and in the users/administrators and users/owners lists in appsettings.json, and that the port you expose is reachable only from the machine itself unless you terminate TLS in front of it.

Frequently asked questions

Official sources

1. Issues
2. microsoft/IIS.Administration on GitHub
3. README
4. Releases