Installation

Installation Options

Fabric.Authorization has been built with .NET Core 1.1. As a result you have the option of running it on Windows or Linux.

We provide pre-packaged Docker containers if you want to run in Linux on Docker. Below are instructions for installing Fabric.Authorization on Linux with Docker or on Windows.

Installing Fabric.Authorization on Windows Server

Prerequisites

• Windows Server 2008 R2 SP1 or greater with IIS and the .NET Core Windows Server hosting bundle installed. See this article for configuring IIS as a reverse proxy for an ASP .NET Core application.
• URL Rewrite extension installed on the server. You can go here to download.
• Valid DNS name configured for the IIS server configured above, e.g. authorization.fabric.example.com.
• Valid SSL Certificate corresponding to the above configured DNS name installed in the LocalMachine\My certificate store.
• Fabric.Identity installed
• The Fabric.Installer secret from the Fabric.Identity installation.
• CouchDB server (see below for instructions on installing couchdb).

Installation

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

Install-Authorization-Windows.ps1 - the main script that installs Fabric.Authorization
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.Authorization

To install Fabric.Authorization perform the following steps:

1. Extract the Fabric.Authorization.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), including setting the fabricInstallerSecret setting with the installer secret output by the Fabric.Identity installation.
3. Ensure the anonnymous configuration settings are unlocked in IIS.
4. Open a PowerShell console as an Administrator on the target machine
5. Execute the installation script .\Install-Authorization-Windows.ps1. By default the script will look for the Fabric.Authorization.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 specified in the encryptionCertificateThumbprint setting.

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.Authorization. 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 -->
      <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 
           thumb-print of the certificate providing TLS/SSL for the website. -->
      <variable name="encryptionCertificateThumbprint" value="" />
    </scope>
    <scope name="authorization">
      <!-- The path to the location of the zip file that contains the binaries for Fabric.Authorization -->
      <variable name="zipPackage" value="Fabric.Authorization.API.zip" />
      <!-- The root of the web site where you want to install Fabric.Authorization -->
      <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="authorization" />
      <!-- 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 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 URL to Fabric.Identity -->
      <variable name="identityServerUrl" value="http://localhost/identity" />
      <!-- The URL of the root web site that the application is being installed on -->
      <variable name="hostUrl" value="http://localhost"/>
    </scope>
  </settings>
</installation>

Unlock Authentication Config

Before running the script, you'll need to unlock the system.webServer/security/authentication/anonymousAuthentication configuration section 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

After you run the script there is one additional manual step that needs to be performed:

• Grant the account running the website access to read the private key of the certificate specified in the -sslCertificateThumbprint parameter. This allows the web app the ability to decrypt the configuration settings in the web.config.

Installing Fabric.Authorization on Docker (Linux)

Prerequisites

• Docker version 17.06 ee/ce or later installed on a Linux machine.
• Docker swarm enabled
• A valid DNS name mapped to your docker host
• A valid SSL certificate for your docker host and the corresponding private key, this SSL certificate should be valid for the DNS name configured for the docker host
• The exported SSL certificate for the host Fabric.Identity is running on if is not issued by a trusted root CA
• Ports 80 and 443 available on your docker host
• An Azure Application Insights telemetry key
• CouchDB and the CouchDB URL
• Docker secrets set up for the CouchDB Username and Password (our Docker couchdb install script will set these if you use it.)
• Internet connectivity on the docker host to pull the images
• Network connectivity to the host that Fabric.Identity is installed on
• The docker host for the ports that Fabric.Authorization is running on (80,443) will also need to be accessible from where end users will be accessing relying party applications

curl -sSL https://healthcatalyst.github.io/InstallScripts/installauthorization-swarm-simple.sh | sh /dev/stdin [authority] [authcert] [authkey] [couchproxy] [appInsightsInstrumentationKey] [authorizationverion]

• authority: the URL to Fabric.Identity
• authcert: the path to an ssl certificate for running Fabric.Identity over SSL.
• authkey: the path to the private key of a certificate for running Fabric.Identity over SSL.
• couchproxy: the URL to the couch db proxy
• appinsightskey: the instrumentation key for a valid app insights instance where logs and telemetry can be sent.
• authorizationversion: the docker image tag of the version of Fabric.Authorization you want to install.

Install CouchDB

Install CouchDB on Windows

For full details about installing CouchDB on windows, refer to this document.

• Download CouchDB binaries
• Run the msi, accepting the defaults for installation
• Open Fauxton
• Create an admin user
• Create a database named "Identity"

Install CouchDB on Docker Swarm

Alternatively, you can install CouchDB on Docker. If you have a Docker swarm available, you can use this script to install CouchDB.

curl -sSL https://healthcatalyst.github.io/InstallScripts/installcouchdbcluster-swarm.sh | sh /dev/stdin [couchdb username] [couchdb password] [path to pem file]

Where:

[couchdb username] is the username you want your couch db admin user to have. [couchdb password] is the password you want for your couch db admin user. [path to pem file] is the path to a pem file that has the public and private keys of a valid certificate that corresponds to the hostname of your docker host.

This script will setup CouchDB to run in a 3 node swarm, with HAProxy handling the load balancing across the nodes. The cluster can be accessed securely at https://yourdockerhost:5985.