Microsoft IIS Administration Preview 1.0.38: Introducing the Files API

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.

With our previous preview release of the IIS Administration API we gave a sneak-peek of a new way for administrators to remotely manage their IIS machines. The API paired up with the web UI at manage.iis.net provides a method to administer IIS from the browser regardless of the machine that one is utilizing. We have been grateful for all the feedback that has been given to us and are constantly working to make this tool what IIS users want. One consistent piece of feedback that we were getting was that although the API provided a method to remotely configure IIS, users still had to find alternate methods to connect to the machine to deploy/update files. Since the last preview release of the IIS Administration API, exciting changes have been made. We have added a file system API that enables consumers to manage the files that are essential to the proper function of their web servers. 

File System API capabilities:

  • Browse the file system on the machine, including metadata for files and folders
  • Create, edit or delete files and folders
  • Upload files in one request or upload in chunks via HTTP content-range requests
  • Download files in one request or download in chunks via HTTP range requests
  • Create temporary download links for files that allow the file to be downloaded via a browser
  • Browse the virtual file structure of a website including applications and virtual directories
  • Copy/move files and folders
  • Restrict the API's access to the file system via the application settings file.

File API Root

The entry endpoint for the files API is /api/files. This endpoint lists a set of directories which act as roots to the file system. Only files and folders under these directories are accessible. This set of root directories is configurable in the application settings file (appsettings.json). By default the only access allowed to the file system is read access to paths beginning with %systemdrive%\inetpub. Attempting to access a directory that is not under a location listed in the files settings will result in an HTTP 403 (Forbidden) response. The appsettings.json file can be found at C:\Program Files\IIS Administration\<Installed Version>\Microsoft.IIS.Administration\config\appsettings.json.

Adding file system privileges in appsettings.json

{
  .
  .
  .
  "files": {
    "locations": [
      {
        "alias": "Inetpub",
        "path": "%systemdrive%\\inetpub",
        "claims": [
          "read",
          "write"
        ]
      }
    ]
  }
}

Using the previous appsettings.json snippet will yield the following result when requesting the /api/files endpoint. GET /api/files

{
  "files": [
    {
      "name": "inetpub",
      "id": "{id}",
      "type": "directory",
      "physical_path": "C:\\inetpub"
    }
  ]
}

The File Resource

Consumers of the files API will have access to the new file resource. The file resource is used to represent both files and directories. The two can be distinguished by reading their type property. If the resource type is a file, then the content will be available from the api at /api/files/content/{id}. If the resource type is a directory, then the children of the directory can be listed at /api/files?parent.id={id}. These links are available through the _links property of the resource. 

File resource

{
    "name": "iisstart.png",
    "id": "{id}",
    "type": "file",
    "physical_path": "C:\\inetpub\\wwwroot\\iisstart.png",
    "exists": "true",
    "size": "98757",
    "created": "2017-01-09T18:08:33.5130112Z",
    "last_modified": "2017-01-09T17:48:13.6180477Z",
    "last_access": "2017-01-09T17:48:13.6180477Z",
    "e_tag": "1d26aa08c67ed45",
    "parent": {
        "name": "wwwroot",
        "id": "{id}",
        "type": "directory",
        "physical_path": "C:\\inetpub\\wwwroot"
    },
    "claims": [
        "read",
        "write"
    ],
    "_links": {
        "content": {
            "href": "/api/files/content/{id}"
        },
        "copy": {
            "href": "/api/files/copy"
        },
        "downloads": {
            "href": "/api/files/downloads"
        },
        "move": {
            "href": "/api/files/move"
        }
    }
}

Editing a File

There are two things that come up when discussing editing a file. The first is editing the metadata of the file. This includes properties such as the last modified and creation dates. Editing file and folder metadata via the API is similar to all other resources. A PATCH request sent to the file resource at /api/files/{id} with the desired state will update the file. The second method of editing a file is altering the file content. The content of a file can be altered by sending a PUT request to the content link for the file at /api/files/content/{id}. The PUT request should send a raw byte stream as the request body which will become the new content of the file. This operation also supports the HTTP 'Content-Range' header to enable altering only a section of a given file.

Editing the second 500 bytes of a 1000 byte file using a PUT request with the content-range header

    PUT /api/files/content/{id}
    Access-Token: Bearer {Access-Token}
    Content-Range: bytes 500-999/1000
    Content-Length: 500
    Content-Type: application/octet-stream

Creating a File

Creating a file is done by submitting a POST request to the /api/files endpoint. When creating a file the user must specify the desired name, type, and parent of the file.

Creating a file. POST /api/files

{
  "name": "MyFile.txt",
  "type": "file",
  "parent": {
    "id": {id}
  }
}

Moving/Copying a File

Move and copy operations are performed by sending a POST request to the /api/files/move and /api/files/copy endpoints respectively. When one creates a move or copy operation, a progress resource is returned that indicates the progress of the operation. This resource can be requested over and over in order to await completion of the operation.

Copying a file (file) to a another directory (parent). POST /api/files/copy

{
  "name": "myOptionalName.txt",
  "file": {
    "id": {sourceId}
  },
  "parent": {
    "id": {destinationId}
  }
}

Creating a Download Link

The simplest way to download a file is through the files content resource at /api/files/content/{id}. The drawback of this endpoint is that it requires an access token so there is no way to perform standardized downloads from clients like a browser. To enable this behavior the API provides a way to create temporary download links that can be used to download a specific file. A download link can be created by sending a POST request to the /api/files/downloads endpoint that specifies which file should be made available and optionally how long it should live. The default lifetime of a download link is five seconds.

Creating a temporary download link for a file. POST /api/files/downloads

{
  "file": {
    "id": {id}
  },
  "ttl": {optional time-to-live in milliseconds}
}

Web Server File Resource

One of the powerful features of IIS is the ability to create virtual file hierarchies through the use of applications and virtual directories. For example, a web site may have access to directories that do not exist directly under the web site's directory on the file system. Understanding the virtual file structure of a web site is critical to ensuring that the web site behaves as expected. We have developed an API endpoint that exposes this virtual file structure at /api/webserver/files. This endpoint treats websites as the root of a virtual file system. All files under this route have paths that are relative to the web site and they indicate which web site they belong to. These web file resources are similar to the resources found under /api/files except they are read only and meant for navigating the virtual file hierarchy. To manipulate the resources found under the web server files route, one can use the file_info property which is a reference to the /api/file resource for that web file.

Web Server File Resource

{
    "name": "iisstart.png",
    "id": "{id}",
    "type": "file",
    "path": "/iisstart.png",
    "parent": {
        "name": "",
        "id": "{id}",
        "type": "application",
        "path": "/"
    },
    "website": {
        "name": "Default Web Site",
        "id": "{id}",
        "status": "started"
    },
    "file_info": {
        "name": "iisstart.png",
        "id": "{id}",
        "type": "file",
        "physical_path": "C:\\inetpub\\wwwroot\\iisstart.png"
    }
}

Files UI

This new API surface provides the foundation to enable many new types of tools including user interfaces, deployment scripts, and file transfer systems. We have already developed a file UI built in to manage.iis.net that provides an experience similar to other file explorers. Users who obtain the newest preview release of the API will notice a files tab in the web site viewer the next time they visit manage.iis.net. This file explorer has many features such as breadcrumb navigation, text navigation, forward and back button integration, drag and drop support, and others. We even have plans to add a built-in file editor that will allow you to make changes to files as needed.

File System UI capabilities:

  • Browse the virtual file hierarchy rooted at a web site.
  • Copy multiple files at once using the upload button.
  • Copy files via drag and drop.
  • Select multiple folders using ctrl+click, shift+click, and ctrl+a.
  • Navigate using breadcrumbs, typing virtual paths, or using forward and back buttons.
  • Create, rename, and delete files and folders.

Creating a folder, uploading, and moving files in the new file explorer at manage.iis.net

Access Required

The file API comes with restricted file system access. A clean installation will only be able to read files from the directory %systemdrive%\inetpub (C:\inetpub in most cases). Attempting to access directories outside of this location or attempting to perform write operations will display an 'Access Denied' message. To avoid the access errors make sure to allow access to all desired file system locations in the appsettings.json file.

Attempting to perform a read/write operation without the required privileges.

Breaking Changes

Creating web sites, applications and virtual directories now requires read access for the target directory. With the addition of settings to restrict access to the file system, all parts of the API that previously interacted with physical paths have been affected. This means that on a clean installation of the API sites, applications, and virtual directories can only be created in %systemdrive%\inetpub. This change also effects logging, compression, and any other IIS feature that has the capability to set a target directory.

Attempting to create a site in a directory that does not have read access.

Obtaining Microsoft IIS Administration Preview 1.0.38

The best way to obtain the IIS Administration API is from manage.iis.net/get. We wrote about how to install the API and connect to the web UI in a previous blog post.

7 Comments

  • How does this REST implementation handle concurrent operations against IIS like binding changes, adding sites and application pools?

  • Currently the last request wins when setting IIS configuration. The API supports transactions which can sequentially set the configuration and prevent other requests from interfering. When a transaction is started, mutating requests that don't specify the transaction I.D. will fail and configuration changes won't take place until the transaction is completed. The docs that we just released at https://docs.microsoft.com/en-us/iis-administration don't mention transactions currently but we are working on the documentation and will prioritize transactions.

  • @fds,
    Creating Web Sites, Web Application and Virtual Directory requires that the API Files section (in appsettings.config) is configured to allow read access to the target path (or any root of it). It's only for administration purpose. It doesn't affect runtime operations.
    The reason behind was that web entities (like websites and other mentioned) can expose system-wide files if not careful. It's not hard to configure web apps that serve from almost any location, which may elevate security risks. In addition, IIS Administration API doesn't require local Administrators privileges to manage IIS (IIS Administrators Group is sufficient). Therefore we would like to give system Administrators control over where IIS is allowed to operate.
    By default %systemdrive%\inetpub is allowed. But we are aware that often IIS is configured to serve websites and content from UNC shares or other dedicated locations. Authorize these locations in the appsettings.json and IIS Administration API will gate the access accordingly.

    Example:

    "files": {
    "locations": [
    {
    "alias": "WebSites",
    "path": "d:\\iis\websites",
    "claims": [
    "read"
    ]
    },
    {
    "alias": "WebSites-On-UNC",
    "path": "\\fileshare\iis\websites",
    "claims": [
    "read"
    ]
    }
    ]
    }

  • Hi, I'm trying to edit the appsettings.json to configure the API Files section as you show in this page. But each time I try to save the file it says it's used by a process. I tried everything: stopping the IIS Admin service, stopping the web server, killing processes, but it's always the same. Any clue?
    Thanks,

  • @Andrea
    Did you already take ownership of the appsettings.json file and give yourself permission?

    Also the IIS Administration API service is called "Microsoft IIS Administration" in the services explorer. I believe the previous IIS management service uses the name "IIS Admin" that you mentioned.

    There's a handy tool called process explorer that you can get here that is super useful for finding what process is holding a file. https://docs.microsoft.com/en-us/sysinternals/downloads/pro

  • Hello,

    We have the same problem as mentioned by Andrea R. We cannot save the config file as it is owned by the SYSTEM account. Even starting notepad++ in administrator mode does not help. We checked the permissions and saw that even users from the administrators group do not have write permissions on this file. Do you know some way to fix this?

  • @henk

    You nailed it. The reason that the config file cannot be edited in notepad++ as administrator is because administrators don't have write access by default and the file is owned by the SYSTEM account.

    To edit this file:

    1. Change the owner of the file to Administrators
    2. Give write permissions to Administrators or the account being used to edit the file.

    You can do this from an elevated command prompt with the following commands. Just replace 2.2.0 with the version that you have installed.

    takeown /f "C:\Program Files\IIS Administration\2.2.0\Microsoft.IIS.Administration\config\appsettings.json" /a
    icacls "c:\Program Files\IIS Administration\2.2.0\Microsoft.IIS.Administration\config\appsettings.json" /grant Administrators:(M)

    Let me know if that solves the issue.

    It is worth mentioning why the file is configured in this manner by default. The IIS Administration service runs on the machine as the System account, meaning it is one of the most privileged processes. This default ACL protects from unintentionally modifying the service. We want users/administrators to never have to access this file. In our 2.2.0 release we added an API endpoint that provides a way to change the files settings in the appsettings.json. Unfortunately to change security requirements such as removing Windows Authentication or granting access to additional Windows accounts the appsettings.json file must be edited manually.

Comments have been disabled for this content.