Installing Fabric.Identity

Installing Fabric.Identity on Windows

Prerequisites

• Domain joined Windows Server 2008 R2 SP1 or greater with IIS installed. See this article for configuring IIS as a reverse proxy for an ASP .NET Core application.
• Valid DNS name configured for the IIS server configured above, e.g. identity.fabric.example.com.
• Valid SSL Certificate corresponding to the above configured DNS name installed in the LocalMachine\My certificate store.
• A service account (with password) in the target domain that has read access to Active Directory for the purpose of making LDAP queries.
• Connectivity to the domain controller over port 3269
• Cookies are required to store session state on browser clients.

Installation

Packaged in the Fabric.Identity.zip (which can be obtained from our releases page) are PowerShell scripts and an install.config file that automate the installation of Fabric.Identity. The scripts and config are:

Install-Identity-Windows.ps1 - the main script that install Fabric.Identity
Fabric-Install-Utilities.ps1 - a module that contains common function for installing Fabric components
install.config - an xml based config file that provides input values to the installation script for installing Fabric.Identity

To install Fabric.Identity perform the following steps:

1. Extract the Fabric.Identity.zip package to a folder on the target machine
2. Update the install.config settings appropriately for your environment (see below for details on the configuration settings)
3. Ensure the anonnymous and windows authentication configuration settings are unlocked in IIS.
4. Open a PowerShell console as an Administrator on the target machine
5. Execute the installation script .\Install-Identity-Windows.ps1. By default the script will look for the Fabric.Identity.API.zip file, the install.config file and the Fabric-Install-Utilities.psm1 files in the same directory as the installation script.
6. Grant the account running the website access to read the private key of the certificate(s) specified in the primarySigningCertificateThumbprint and encryptionCertificateThumbprint settings.
7. Take note and save in a key vault the Fabric.Installer client secret. This value is used to register other client applications with Fabric.Identity to allow them to delegate authentication to Fabric.Identity.

install.config

The installation script reads installation parameters from an install.config file. The install.config file has two sections. A common section that can be used by other applications during installation and a section specific to Fabric.Identity. Below is an example install.cofig with comments describing each parameter:

<?xml version="1.0" encoding="utf-8"?>
<installation>
  <settings>
    <scope name="common">
      <!-- The encrypted Fabric.Installer client secret, used for registering additional API's
           and Clients with Fabric.Identity. After Fabric.Identity is installed, the secret will 
           be written to this setting -->
      <variable name="fabricInstallerSecret" value="" />
      <!-- The thumb-print of an SSL certificate to use for encrypting/decrypting sensitive information 
           in the config. For initial installation it is recommended to use the thumbprint of the 
           certificate providing TLS/SSL for the website.-->
      <variable name="encryptionCertificateThumbprint" value="" />
    </scope>
    <scope name="identity">
      <!-- The path to the location of the zip file that contains the binaries for Fabric.Identity -->
      <variable name="zipPackage" value="Fabric.Identity.API.zip" />
      <!-- The root of the web site where you want to install Fabric.Identity -->
      <variable name="webRoot" value="C:\inetpub\wwwroot" />
      <!-- The name of the app and app pool that will be created in IIS -->
      <variable name="appName" value="identity" />
      <!-- The user account for the app to run under in IIS -->
      <variable name="iisUser" value="IIS_IUSRS" />
      <!-- The thumb-print of an SSL certificate to use for signing access and identity tokens. 
           For initial installation it is recommended to use the thumb-print of the certificate 
           providing TLS/SSL for the website. -->
      <variable name="primarySigningCertificateThumbprint" value="" />
      <!-- The thumb-print of an SSL certificate to use for encrypting/decrypting sensitive information 
           in the config. For initial installation it is recommended to use the thumb-print of the 
           certificate providing TLS/SSL for the website.-->
      <variable name="encryptionCertificateThumbprint" value="" />
      <!-- The URL:port of the CouchDB server -->
      <variable name="couchDbServer" value="http://127.0.0.1:5984" />
      <!-- The username for the CouchDb server -->
      <variable name="couchDbUsername" value="" />
      <!-- The password for the CouchDb server -->
      <variable name="couchDbPassword" value="" />
      <!-- An Azure Application Insights instrumentation key that allows telemetry to be recorded in 
           Azure Application Insights. If no instrumentation key is provided, no telemetry will be sent. -->
      <variable name="appInsightsInstrumentationKey" value="" />
      <!-- The name of the IIS website to install the application under -->
      <variable name="siteName" value="Default Web Site" />
      <!-- The fully qualified URL of the root web site that the application is being installed on -->
      <variable name="hostUrl" value="http://localhost" />
      <!--The fully qualified DNS name of the LDAP server (usually a domain controller in Windows) -->
      <variable name="ldapServer" value="localhost"/>
      <!-- The port used to connect to the LDAP server -->
      <variable name="ldapPort" value="3269"/>
      <!-- The user name used to authenticate to the ldap server -->
      <variable name="ldapUserName" value=""/>
      <!-- The password for the user used to authenticate to the ldap server -->
      <variable name="ldapPassword" value=""/>
      <!-- Defines whether to connect to the LDAP server using SSL -->
      <variable name="ldapUseSsl" value="true"/>
      <!-- The base domain to search in LDAP, e.g. DC=example,DC=org -->
      <variable name="ldapBaseDn" value=""/>
    </scope>
  </settings>
</installation>

Unlock Authentication Config

Before running the script, you'll need to unlock the system.webServer/security/authentication/windowsAuthentication and system.webServer/security/authentication/anonymousAuthentication configuration sections in IIS Manager:

• Open IIS Manager
• Click the server name in the tree on the left
• Right hand pane, Management section, double click Configuration Editor
• At the top, choose the section system.webServer/security/authentication/anonymousAuthentication
• Right hand pane, click Unlock Section
• At the top, choose the section system.webServer/security/authentication/windowsAuthentication
• Right hand pane, click Unlock Section