Installation guide

Owned by Morten Lindequist Køhler
Last updated: Mar 20, 2024 by Jan Wisén Francke-Larsen
5 min read

The Perfion API Service must be installed as a separate website under Internet Information Services (IIS).

Pre-requisites

The Perfion API Service requires that the Microsoft .NET Framework 4.8 and Internet Information Services (IIS) is installed.

IIS needs to be configured for executing ASP.NET 4.x applications. You can run the following two commands in Windows PowerShell it install/configure the necessary features.

  1. Install/configure ASP.NET 4.x
    Install-WindowsFeature NET-Framework-45-Features -IncludeAllSubFeature

  2. Install/configure IIS and necessary features
    Install-WindowsFeature Web-Server,Web-WebServer,Web-Common-Http,Web-Default-Doc,Web-Dir-Browsing,Web-Http-Errors,Web-Static-Content,Web-Http-Redirect,Web-Health,Web-Http-Logging,Web-Custom-Logging,Web-Request-Monitor,Web-Http-Tracing,Web-Performance,Web-Stat-Compression,Web-Security,Web-Filtering,Web-Basic-Auth,Web-App-Dev,Web-Net-Ext45,Web-Asp-Net45,Web-ISAPI-Ext,Web-ISAPI-Filter,Web-Mgmt-Tools,Web-Mgmt-Console

Install as a new website

Follow these steps to install the Perfion API Service:

  1. Extract all files from the API Service zip-file into the root of the folder where you want them located (typically c:\inetpub\PerfionAPI)

  2. Create a sub-folder under Perfion called Cache (e.g. c:\inetpub\PerfionAPI\Perfion\Cache)

  3. Make sure IIS user has full control of Cache folder (as it needs to write to this folder).

  4. Create a new IIS Website and set its content directory to the chosen location.

  5. Create a HTTPS binding on the website and assign a suitable SSL certificate.

  6. Ensure that you have the Start Mode of the Application Pool set to AlwaysRunning.

Step 6

 

Create Web.config file

The installation package contains a file called Web.config.example. Create a copy of this file (in same folder) and name it Web.config.

Changes to Web.config file

You need to edit the following connection string in the Web.config file to match the desired Perfion system and database as follows.

<connectionStrings> <add name="PerfionConn" connectionString="Data Source=(local);User ID=dbuser;Password=dbuser-password; Initial Catalog=PerfionDemo;PerfionUserID=admin;PerfionPassword=admin-password;PerfionLanguage=;"/> </connectionStrings>

The first part of the connection string is just a normal connection string. The last properties of the connection string are Perfion username, password and optionally language.

Configuring secure access

We strongly suggest that authentication is enabled on the Perfion API, effectively limiting who can call the API and retrieve, update or delete data. Perfion API Service Authentication can be enabled in the Web.config file by setting SecureApiService to true:

<add key="Perfion.SecureApiService" value="true"/>

This will force the API Service to require authorization. If this setting is enabled and the caller is not authenticated, the API will return an error.

NOTE: When authentication is enabled, only the GetData endpoint (see Perfion API Reference Guide) is protected by the authentication. The Image-, File-, and Report-server remains unprotected.

In Perfion versions before 5.0 the authentication only limits access to the API. So when authenticated, the user can select all data in Perfion. Being Super User or Administrator the user could even Insert, Update and Delete data.

From version 5.0 this has changed, so that the API will check whether the authenticated user has access to the data using the permissions in Perfion. This both effects reading and editing data. If some data is “Read only” it will not be shown to the user doing a select. Furthermore a user needs Edit-access to features who’s data he/she want to update. If a user tries to update data he/she does not have edit-access to, the Perfion API will return an error message. Super Users and Administrators always has read and edit access to all data in Perfion, just as they have in the clients. A notable exception to this is features that are “Read only”. They cannot be modified from neither the API nor the clients, but only be changed thorugh an Import run by an action.

Configure Azure AD authentication

To enable Azure AD authentication against the Perfion API Service, you (1) need to configure an App registration within the Azure AD and (2) configure the Perfion API Service use validate the token correctly.

App Registration

First you need to register the Perfion API Service as an app in your Azure AD. Please refer to Microsoft’s documentation (https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) for details.

The App Registration should be of type Web and the Redirect URL should be set to the URL where the API is running. Supported account type should be single tenant, meaning that only users from your Azure AD are allowed to authenticate against the service.

Under API permissions, ensure that the application has the ‘User.Read’ permission and that consent has been granted.

Under Expose an API, make sure that the Application URI is set; you can use the default value suggested. Add a scope called PerfionAPI. Consent should be set to Admins only.

Configure Perfion API Service

There are three settings that needs to be updated in the Perfion API Service web.config file to enable the service to validate the tokens issued.

Setting

Description

AzureAD:Tenant

This setting can be found via the Azure Portal on the Overview page of the Azure AD to be used.

AzureAD:ClientId

The Client ID of the App Registration. This can be found on Overview page on the App Registration.

AzureAD:Audience

The Application ID URI of the App Registration. This can be found on the Overview page on the App Registration

Consider disabling insecure SSL & TLS protocols and ciphers

As previously mentioned, Perfion strongly suggest that the Perfion API Service is configured to only allow encrypted HTTPS connections. Best practice is to only allow the use of TLS 1.2 or newer, and to disable older insecure protocols and ciphers.

Disabling of SSL- and TLS protocols older than 1.1 is done on the server that is hosting the Perfion API Service. This is done via the Windows system registry database.

Please refer to https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings#tls-dtls-and-ssl-protocol-version-settings for details on how to set the relevant settings.

You should consider disabling the RC4 and Tripple DES 168 ciphers as well. Please refer to https://docs.microsoft.com/en-us/troubleshoot/windows-server/windows-security/restrict-cryptographic-algorithms-protocols-schannel for details on how to set the relevant settings.

Testing and using the Perfion API Service

To test the Perfion API Service you can use the “Perfion API Tester” utility program as shown below. This program can be downloaded from the Perfion Knowledge Base:

Please refer to Perfion API Reference Guide for information about how to use the API Service.

Perfion API Service Upgrade

You should upgrade the Perfion API Service every time you upgrade your Perfion clients.

Upgrading is simple:

  1. Download newest API Service zip-fil from Perfion Knowledge Base and unzip content

  2. Stop Perfion API Website in IIS

  3. Copy all unzipped files to the folder containing your Perfion API Service files (typically c:\inetpup\PerfionAPI)

  4. Overwrite all existing files

  5. Restart Perfion API Website in IIS

The web.config file (which amongst other things contains the database connection string to the Perfion database) will not be overwritten as the zip-file only contains a Web.config.example file.

NOTE: With a new Perfion API service version, changes to the web.config file might be necessary! It is therefore important to check if the web.config.example includes changes over the already installed web.config file.

You could also simply create a new web.config by copying the web.config.example and adding your necessary connection changes.

Common Issues to get the API Service running

Site Security Settings

The most often encountered problems in getting the service running are related to security issues. The right system users must be assigned proper access rights to the folder that contains the site files. The names of the users vary from system to system, so you need to refer to Microsoft guidelines for this setup.

IIS versus .NET Framework installation order

If the Internet Information Server was installed on the machine after the Microsoft .NET Framework, then it has not been configured correctly to use the .NET Framework.

You need to open the Command Prompt and run the “aspnet_regiis.exe” with the option –I to install the .NET Framework correctly for the IIS. “aspnet_regiis.exe” is usually found in the directory “c:\Windows\Microsoft.NET\Framework\vX.X.XXX\”.