Setting Up the IIS Administration API

This topic outlines the setup tasks required for the IIS Administration API, in order for the Management Pack to collect data properly:

• Installing the IIS Administration API

• Configuring the IIS Administration API

• Assigning an IIS Least-Privileged User

• Generating an Access Token

• Re-enabling Authentication

Installing the IIS Administration API

1. Enable and start your Windows Server running IIS.

2. As an administrator, install the IIS Administration API from: github.com/microsoft/IIS.Administration/releases/tag/v2.2.1

   Note:

   Installing the IIS Administration API should automatically open port 55539, but we recommend ensuring it is opened prior to continuing.

3. Restart the Windows Server running IIS.

Configuring the IIS Administration API

1. Go to directory: C:\Program Files\IIS Administration<version of the api>\Microsoft.IIS.Administration\config.

2. Change the owner of the appsettings.json file from SYSTEM to Administrators group.

3. Edit the appsettings.json file by configuring the following properties:

   • Set security.require_windows_authentication to false.

   • Set security.access_policy.api.users to Everyone.

   • Set security.access_policy.api.access_key to false. (NOTE: This will temporarily disable authentication, which will be re-enabled after generating an access token later on.)

   • Add the security.access_policy.api.read_only property and set it to true.

   • Example excerpts from the appsettings.json file of the applicable property settings are shown below:

       "security": {
         "require_windows_authentication": false,
       
         "access_policy": {
           "api": {
             "users": "Everyone",
             "access_key": false,
             "read_only": true
           },
         }
       },

4. Restart the IIS Administration API service.

Assigning an IIS Least-Privileged User

In Microsoft's IIS Administration documentation, the Application Settings topic (Security section) discusses the default access 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."

The Management Pack for IIS uses an access token for authentication. Setting the require_windows_authentication property to false as indicated in Configuring the IIS Administration API above allows the user to authenticate using that access token, which will be generated next in the Generating an Access Token section.

Adding the Windows user to the IIS API administrators and owners roles allows that user to generate the access token and execute requests to the API using that token.

Generating an Access Token

Next, you must generate an access token to be used for authentication when Creating a Credential:

1. Open https://localhost:55539/.

2. Click on the ACCESS KEY link.

3. Click the Create Access Key button. Set the key name and expiration period.

4. Save the access key for use when Creating a Credential.

Re-enabling Authentication

Now that your access token has been generated, you must go back into the appsettings.json file and re-enable authentication:

1. Go to directory: C:\Program Files\IIS Administration<version of the api>\Microsoft.IIS.Administration\config.

2. Edit the appsettings.json file by configuring the following properties:

   Set security.access_policy.api.access_key to true.

   Example from appsettings.json file:

   "access_policy": {
         "api": {
           "users": "Everyone",
           "access_key": true,
           "read_only": true
         },
       }

3. Restart the IIS Administration API service.