Microsoft IIS Administration API 2.0.0

The Microsoft IIS Administration API is making IIS administration simpler than ever before. If you are unfamiliar with the API, check out our earlier post for an introduction.

Microsoft IIS Administration API 2.0.0 has just been released which features a range of 'under the hood' improvements to the API. These changes aim to make installing, running, and configuring the API simpler while at the same time opening the door for new types of features in the future.

Configuration Changes

When the IIS Administration API is installed, it is configured to require Windows authentication for all requests. Previously, the Windows authentication and other security related configuration resided in a file named web.config. This name may seem familiar because it is the same file that IIS uses to configure settings for web sites and applications. Since the IIS Administration API was previously using a self-hosted version of IIS to run as a service it was able to utilize the IIS configuration system for capabilities such as authentication and authorization. Now, the IIS Administration API no longer self hosts IIS, and instead uses the ASP.NET Core HttpSysServer. This means that there is no more web.config file. The settings that were previously in the web.config file have been transformed and moved into the application's settings file (appsettings.json). None of the paradigms that the IIS Administration API has been using for security have changed. Only the location of the configuration and the way the settings look have been modified. Many use cases have arisen in which users wished to make modifications to the security settings, and this new configuration system was designed to make these modifications more intuitive.

New Security Section

In previous releases, all of the authentication and authorization settings for the API were contained in the aforementioned web.config file despite the fact that there was another configuration file in use named appsettings.json. Now that the web.config file has been removed, the security settings have been added to the appsettings.json file in a new security section.

The default location for the appsettings.json file is %ProgramFiles%\IIS Administration\2.0.0\Microsoft.IIS.Administration\config\appsettings.json

  "security": {
    "require_windows_authentication": true,
    "users": {
      "administrators": [
        "DOMAIN\\UserName"
      ],
      "owners": [
        "DOMAIN\\UserName"
      ]
    },
    "access_policy": {
      "api": {
        "users": "administrators",
        "access_key": true
      },
      "api_keys": {
        "users": "administrators",
        "access_key": false
      },
      "system": {
        "users": "owners",
        "access_key": true
      }
    }
  }

What It Means

require_windows_authentication: A flag that, when true, requires every request to the IIS Administration API to have Windows authentication.

users: The users part of the security section is a map of Windows users/groups to certain roles within the API. In a default installation administrators can access the IIS Administration API as well as generate access tokens. Owners have the highest level of privelege and can perform operations such as setting an application pool identity to LocalSystem.

access_policy: Access policies specify a set of requirements to access certain areas within the API. IIS Administration 2.0.0 comes with three different access policies, api, api_keys, and system. The api access policy governs general access to the API. The api_keys access policy specifies the requirements to generate API keys (access tokens). The system access policy protects the most privileged operations within the API.

As shown, each access policy has a set of requirements. The users requirement specifies which roles from the users section have access to the resources that the access policy governs. The access_key requirement specifies whether the resources protected by that access policy require an access token.

There are two additional requirements that can be specified in access policies named forbidden and read_only. The forbidden requirement blocks all access to the resources guarded by the effected access policy. As an example, if the forbidden requirement was placed in the api_keys access policy then api keys could no longer be generated by any user. The read_only requirement ensures that all requests to the resources guarded by the effected access policy are GET requests. An example use case would be to place the read_only requirement in the api and system access policy to deploy a read only version of the IIS Administration API.

Simpler Installation

With the 2.0.0 release, the IIS Administration API has removed multiple dependencies leading to a quicker installation and a thinner footprint on the machine. The ASP.Net Core Module, IIS, and IIS sub-features are no longer required for installation, meaning the only requirement left is .NET Core 1.0 (LTS). It is worth mentioning that the IIS Administration API installer automatically installs this dependency if it is not on the machine, so there is no need to install it as a prerequisite. These changes have improved the experience of installing the API on new machines, and now IIS and the IIS Administration API can even be installed at the same time.