Introducing the IIS Administration API

IIS is a mature technology with a large amount of configuration available. Historically the configuration of IIS has been done through WMI, Appcmd, PowerShell, and graphically through IIS Manager. All of these technologies have continued to serve their purpose, allowing users to configure the web server to meet their needs. Recently the IIS team has been working on a project to open up IIS configuration even more by creating a REST API that exposes the configuration system. This API is not meant to replace any of the existing configuration access mechanisms, but stand beside them and offer an open method for interacting with IIS. The REST API communicates with HTTPS making it accessible from any device that knows how to send a web request. This allows IIS to be configured more freely and opens the door for configuration clients that were not possible before, such as mobile applications.

Today we want to not only let everyone know that we are working on a REST API for IIS, we also want to let you see it. The API that we have created has a built in tool called the API Explorer that allows those with access to the API to browse the entire API surface. This means once you have a link to the root URL of the API you can navigate to this tool and browse all of the API that is available. Here is a picture of the API Explorer in action displaying an application pool resource.

image

Through this API Explorer you can browse the configuration resources of IIS such as authorization rules, modules, and applications. You can also delete these resources, modify them, and create new ones. We have deployed a read-only version of the API to a virtual machine in Azure to allow those who wish to explore the new API a chance to do so. The API available on this machine could be accessed via a simple HTTP client such as cURL, but for the first time experience we recommend giving the API Explorer a look to see what the tool has to offer.

Before connecting to this API let’s touch on the current authentication mechanisms that are in place to help keep it locked down. By default, the entire API is locked down with Windows authentication so that only administrators have access. This default behavior can be modified because, as is the case with many REST APIs available today, the Microsoft IIS Administration API mandates that an Access Token be sent with every request to the API. These access tokens can only be generated by Administrators on the machine that the API is installed on. In practice access tokens would be assigned to a specific user or group. For the purposes of the demo we have generated an access token for public use.

When initially connecting to the API Explorer you will see the following screen.

image

We have relaxed the requirement for windows authentication to connect to the demo API. This means the only authentication mechanism required is the access token. Once you input your access token into the input form and click connect you will have full access to the API in the API Explorer tool from your browser.

image

The API has been built with HAL (Hypertext Application Language). Utilizing HAL allows APIs to have built in discoverability. This is what the API Explorer leverages to create the clickable links that are seen. Through these links the whole API surface is available.

To access the API Explorer on the demo machine that we have deployed, visit https://jimmyca-srv2.cloudapp.net:55539.

To connect to the API, you will need this demo access token:

OgMks6N7CtZTptX2DTnLe8JvkmATOuqw1ZJnZzK1RojeYs251Wlfvg

Client examples

The API Explorer is perfect for discovering what is available from the service we are building. However, if we shift gears to other types of clients then we can demonstrate the power that we gain through the openness of a REST API. Here I give a couple of examples of how the new API allows unbiased interaction with IIS.

PowerShell

The following example uses built-in PowerShell commands to communicate with the IIS Administration API that is available on the public demo. Here we create a headers object that holds our access token for communicating with the API, then we make a request to the websites endpoint. Invoke-RestMethod returns a PowerShell object that is constructed from the JSON response returned from the API. To include HAL in the response object from the API, include the header 'Accept: application/hal+json'.

https://gist.github.com/jimmypc92/00ba9644b3966fc58a13dad80a5c7ef1

image

cURL

Using cURL, the same websites API endpoint can be accessed with the following command:

Note: The API that is hosted on the demo machine is using a self-signed certificate for encrypting HTTPS traffic. By default, cURL commands will reject communication with an untrusted certificate. This behavior is bypassed in the following command by passing the '–insecure' parameter.

curl --insecure https://jimmyca-srv2.cloudapp.net:55539/api/webserver/websites --header "Access-Token: Bearer OgMks6N7CtZTptX2DTnLe8JvkmATOuqw1ZJnZzK1RojeYs251Wlfvg" --header "Accept: application/json"

C# HttpClient

The following gist has an example utilizing the .NET HttpClient to communicate with the API.

https://gist.github.com/jimmypc92/254d5315b861ab53a9ba12033169f9e5

21 Comments

  • What version(s) of IIS will this be available for?

  • Thank you this will be very helpful!

  • Will future versions of IIS have a small, neater configuration file format to accompany this? Right now applicationHosts.config generally gets unreadable, intended for API or UI use only versus the succinct equivalents in Apache and Nginx.

  • @David,

    Our goal is to make this tool available for IIS 7.5 and greater.

    @Chris,

    There are no plans to change the format of the IIS configuration file.

  • Is there any plan to bring this tooling to Azure App Service?
    Maybe as part of the Project Kudu?

  • You've got at least one spam comment on here - guess reCAPTCHA isn't enough anymore.

  • Would be great if this can be made as a module for IIS 7.5

  • @Fabian

    Current development scenarios are for IIS, both remote and on premise but we are always open to options.

    @Satish

    This does not run as a module, perhaps my next blog post will be an overview of the architecture behind the API if you think this would be helpful.

  • I really like this work; a RESTful API for IIS management is a feature great; but what is the user story for install on #NanoServer ? and/or will this also allow configuration on ASPNETCORE web applications running under kestrel via HttpPlatformHandler ?

  • I have developed a web application on visual studio 2010 using c# & sql server 2008, i want to publish that website on my vmware's IIS which is running Windows Server 2012 R2, I uploaded the website on iis using ADD SITE its running but it doesn't accesses the sql database . Please help me its too urgent, if possible u can take my remote access through Team Viewer.

  • @Grahame,

    The Administration API will support Nano Server. Currently we are still discussing what the final install methodology will be for Nano Server. Right now the API is installed onto the machine via a PowerShell script.

    The current API surface available exposes IIS configuration. Any ASP.NET Core application that is hosted using IIS and the AspNetCoreModule will have the capability to leverage IIS features and thus will have settings that can be configured through this API. This service has been designed with extensibility in mind, so future configuration targets and features are not out of the question.

  • when are you expecting to release this REST API ?

  • We have a connectivity problem .
    From mac , with safari and firefox i cannot connect. But working with Chrome on Mac
    I found this http://openradar.appspot.com/6644527 also event viewer security section give me authtentication problem for safari and firefox

    Another issue from Chrome on windows we couldnt connect too ! But Firefox working there ...


  • Hello Vahric,

    Thanks for letting us know about this issue. Windows Authentication is handled differently between browsers and operating systems. Chrome is the most compatible browser and it is what most users opt for.

    Safari is a known problem on Mac but we will have to investigate Firefox.

    I have not heard of any connectivity issues using chrome on Windows. Which version of Windows was causing the problem? Was it when trying to connect to a remote machine or local? Was the machine domain joined?

  • How did you configure it for API to work without windows authentication? I've changed the 'require_windows_authentication' flag to 'false' in the appsettings.json file and restarted the service but it did not work.


  • Hello

    An excellent contribution thanks.

    I have several sites on IIS 7.5, running on a 32-bit OS, which the API supports.

  • You must also change the access policy to allow 'Everyone'. Here is an example.

    "security": {
    "require_windows_authentication": false,
    "users": {
    "administrators": [
    "My-Machine\\jimmy"
    ],
    "owners": [
    "My-Machine\\jimmy"
    ]
    },
    "access_policy": {
    "api": {
    "users": "Everyone",
    "access_key": true
    },
    "api_keys": {
    "users": "administrators",
    "access_key": false
    },
    "system": {
    "users": "owners",
    "access_key": true
    }
    }
    }

    The 'require_windows_authentication' flag is a security net to ensure the whole API requires Windows Authentication. Setting it to false does not actually disable Windows Authentication.

  • @jimmyca Thanks a lot! It is weird that the appsonfig.js file is owned by "System", thus not editable by default. I had to change the ownership and then grant permissions to be able to make changes.

  • Can I try this with IIS 7.0?

  • @Lien Nguyen,

    The IIS Administration API supports IIS 7.5 and above.

  • Can you please release an compiled build on the github site.

    Several people I know have wanted to use this project, but used other api's to provide rest for IIS as they have no desire to install Visual Studio in order to have a rest api for IIS.

    Please release a compiled build to Web Platform Installer so that this can be installed automatically.

Comments have been disabled for this content.