Edit

Application Settings (appsettings.json)

  • Article

All of the application's settings are contained in a file named appsettings.json. Any changes to the appsettings.json file will require restarting the "Microsoft IIS Administration" service to take effect.

The appsettings.json file is located at: %SystemDrive%\Program Files\IIS Administration\<version>\Microsoft.IIS.Administration\config\appsettings.json

CORS

CORS policies allow browser based applications to send requests to the Microsoft IIS Administration API.

Default Settings

The IIS Administration API will not allow CORS for any origin if there are no cors settings present.

Format

For example, the following setting enables CORS:

  "cors": {
    "rules": [
      {
        "origin": "https://contoso.com",
        "allow": true
      }
    ]
  }

rules: A set of CORS rules to control how the API shares resources.

  • origin: The origin, as defined in the CORS specification, to allow or deny. If the wild card character, *, is provided as the origin, that rule will apply to all origins.

  • allow: Indicates whether resources should be shared to the specified origin.

Files

Multiple endpoints require interacting with the file system, such as creating a web site in an existing directory (read) or uploading the content of a file (write). These configuration settings provide a method to restrict these file system interactions. A set of file system locations that are visible to the API are specified. These paths can have read and or write priveleges associated with them.

Default Settings

The IIS Administration API will allow read access to %systemdrive%\inetpub if there are no files settings present.

Format

The following settings allow read/write access to %systemdrive%\inetpub

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

skip_resolving_symbolic_links: A flag specifying whether the system will resolve symbolic links when determining whether a path is allowed. By default this flag is false, meaning symbolic links will be resolved.

locations: A set of file system locations and associated rights specifying what operations are allowed to be performed through the API.

  • alias: A name for the location.

  • path: A root path to assign the list of claims. All files or directories under this path inherit the list of claims unless overridden with a more specific path.

  • claims: Specifies what operations are allowed to be performed on files directories under the path. An empty set of claims means no access will be allowed to that location.

Security

The security section was introduced in IIS Administration 2.0.0. This section specifies the requirements to access the API.

Default Settings

By default the API requires all requests to have valid Windows credentials as indicated by the require_windows_authentication flag. Access to the API's resources, such as websites and applications, and access key manipulation require the user to be in the administrators API role. High privilege operations require the user to be in the owners role. When the API is installed, the administrators and owners roles are automatically populated with the user that executed the installer.

Format

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

require_windows_authentication: A boolean value that specifies whether valid Windows authentication is required for all requests to the API. If true, any request that is not Windows authenticated will be rejected. If false, Windows authentication requirements are determined by the access_policy settings.

users: A mapping between Windows users/groups and roles within the API. Any role can be added, but by default the appsettings.json file contains administrators and owners. These roles are used in the access_policy section to govern access to different sections of the API.

access_policy: Access policies specify a set of requirements to access areas within the API. The IIS Administration API comes with three different access policies, api, api_keys, and system.

  • api: This access policy is for API resources such as web sites, application pools, and files.

  • api_keys: This access policy is for manipulating API keys.

  • system: This access policy is for high privilege actions that are offered by the API, such as changing the identity of an application pool to LocalSystem.

Each access policy has a set of requirements that can be configured. The available requirements are:

users: Specifies which roles from the security.users section are allowed access. To allow all users use a value of 'Everyone'.

access_key: Specifies whether requests are required to have an access token.

read_only: Enforces a read-only mode by restricting all requests to use the HTTP GET method.

forbidden: Blocks all access.

Complete Example

{
  "host_id": "",

  "host_name": "My instance of the IIS Administration API",

  "logging": {
    "enabled": true,
    "file_name": "log-{Date}.txt",
    "min_level": "Error",
    "path": null
  },

  "auditing": {
    "enabled": true,
    "file_name": "audit-{Date}.txt",
    "path": null
  },

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

  "cors": {
    "rules": [
      {
        "origin": "https://contoso.com",
        "allow": true
      }
    ]
  },

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