Installing Hyper-scalable PAS

As a solution that you manage, the Hyper-scalable PAS replicates the infrastructure provided by the Privileged Access Service using your own servers. The installation procedures described in this section, install the necessary software on Windows 2016 Servers to configure them for the following:

  • Management node
  • Web node
  • Background node
  • TCP Relay node (for relay)
  • TCP Relay node (for logging)

The scripts provided for installation have embedded help, which you can view using the Get-Help command; for example, from the script directory type, Get-Help .\Centrify-PAS-NewDeployment.ps1. More detailed help about the parameters is available using the -detail flag; for example, Get-Help .\Centrify-PAS-NewDeployment.ps1 -detail. Additional command output, useful for debugging or watching progress, is available using the -verbose switch.

Note:   All examples in this section, use pas.corpnet.com to refer to the Hyper-scalable PAS hostname.

Before you install

Before you install the Centrify Hyper-scalable PAS software, make sure you have the following:

  • A license key
  • Host certificate from a trusted certificate authority issued for the hostname that you will access Hyper-scalable PAS through.

    Wildcard certificates can be used.

  • Windows 2016 servers for your configuration (see Prerequisites)
  • Redis server (see Prerequisites)

  • Load balancer (see Prerequisites)
  • PostgreSQL-compatible database with all required extensions installed (see Prerequisites for additional details).

  • Data connection information for the following:
    • Redis: server hostname, server port (default is 6379), SSL
    • Database: user name, password, server hostname, server port (default is 5432)
    • Hostname: this is the name of the Installation and must match the hostname used on the certificate
  • Computer designated for the Centrify Connector, if applicable. (Not all services require a Centrify Connector.) See the Privileged Access Service online help and see Installing the Centrify Connector to determine if your configuration requires a connector.

Installation overview

The following is an overview of the steps, organized into phases, required to install Centrify Hyper-scalable PAS. Detailed procedures of each phase are described in subsequent sections.

Phase 1: Installing the Management node

  • Download/copy the Hyper-scalable PAS software package from Centrify to the Windows 2016 server you have designated to be the Management node.

    The installation package includes the following software components: install.ps1, CentrifyPlatform[Build.Number].zip

  • Create the Management node

    To create the Management node, open an elevated PowerShell session and run the install.ps1 script. This expands and installs the CentrifyPlatform[Build.Number].zip (you can optionally set the target directory with the -target parameter). The default directory is C:\Centrify). Once completed, the necessary scripts are available on the Management node for installation and deployment.

    Change to the target directory (C:\Centrify or as specified on the install command line) for all subsequent Management node commands.

Phase 2: Creating a new Installation

  • Create a new Installation (run the Centrify-PAS-NewInstallation.ps1 command on the Management node). This creates the configuration file, verifies the configuration inputs, checks for the Redis and database servers, initializes the database, and checks for the required database extensions.

Phase 3: Creating a Deployment package

  • Create your deployment package (run the Centrify-PAS-NewDeployment.ps1 command on the Management node).

    You can enter a unique Deployment ID using the -ID parameter; otherwise a GUID is used as the Deployment ID.

Phase 4: Deploying Hyper-scalable PAS software to Web, Background, and TCP Relay nodes

  • Copy the Deployment Package from the installations\<hostname>\Deployments subdirectory, to target systems. Once copied, uncompress the package and run the extracted Centrify-PAS-Deploy.ps1 command with the node type as the parameter for each node installation. For example:

    .\Centrify-PAS-Deploy.ps1 -BackgroundNode

    Install the logging node first, if applicable, and then at least one Web node, Background node and TCP Relay node per site installation.

Phase 5: Activating the Deployment

  • From the Management node, activate the deployment using the Centrify-PAS-SetActiveDeployment.ps1 command. Pass in the Deployment ID that you either set as a parameter or received as output from the Centrify-PAS-NewDeployment.ps1 script.

    From the Management node, you can run the command Centrify-PAS-NodeList before activating the deployment to verify the installation and to make sure the nodes are recognized. This should show all of the deployed nodes with an Inactive status. If you run Centrify-PAS-NodeList again (after activating your deployment), you should see that the Web and Background node status is now Active.

Note:   The scripts provided for this installation support the PowerShell switch -verbose which allows you to view additional data about the command.

Phase 1: Installing the Management node

To install the Hyper-scalable PAS, the first step you need to perform is to create the Management node. Download the Centrify Hyper-scalable PAS software package to the computer designated as the Management node and then run the Hyper-scalable PAS installer (install.ps1). The software package contains a directory structure with the following items:

  • Documentation (PDF)
  • CentrifyPlatform[Build.Number].zip (contains the Hyper-scalable PAS installation package)
  • install.ps1 (expands and installs the CentrifyPlatform[Build.Number].zip file)

To install the Management node

  1. On the Management node, log in as a user with administrator rights.
  2. Download the Hyper-scalable PAS software package from Centrify onto the Management node.
  3. Open a PowerShell session in elevated (RunAs Administrator) mode.

    Note:   All PowerShell sessions must be elevated; that is RunAs Administrator mode.

  4. If the installer package is a single zip file, expand it (Expand-Archive in PowerShell, or your preferred unzipping tool).

  5. At the PowerShell prompt, type .\install.ps1 to set up PowerShell cmdlets and tooling on the Management node for cluster installation, management, and deployments.

    See the following for additional parameters.

    Parameter Description
    [-target <String>] Type in the location for the installation (for example, C:\ Centripas; if the target is not included the default is C:\Centrify).

    Type Get-help .\install.ps1 -detail to get information on parameters and switches.

  6. Once installed the following scripts are available in the specified target directory:

    • Centrify-PAS-ForceRemoveNode.ps1
    • Centrify-PAS-GetDeployment.ps1
    • Centrify-PAS-ModifyInstallation.ps1
    • Centrify-PAS-NewDeployment.ps1
    • Centrify-PAS-NewInstallation.ps1
    • Centrify-PAS-NodeList.ps1
    • Centrify-PAS-SetActiveDeployment.ps1
    • Centrify-PAS-WatchLogs.ps1

Phase 2: Creating a new Installation

After creating the Management node, use the Centrify-PAS-NewInstallation.ps1 script, available on the Management node, to create a new Installation. An Installation is an instance of a cluster (all resources, nodes, configuration information, that together provide a single cluster), operating with a single hostname (for example, pas.corpnet.com). The number of systems that comprise the cluster depends on your environment (for minimum requirements, see Prerequisites).

Creating a new Installation requires a dedicated database; this is specified in the configuration or parameters. Each installation must have its own database on a dedicated PostgreSQL server.

The Centrify-PAS-NewInstallation.ps1 script:

  • Creates a directory to hold the generated installation data (in <Centrify PAS Directory>\installations).
  • Creates a configuration in a config subdirectory (inside the installations directory for this Installation). The command parameters are passed as individual parameters or configured in a prepared file.
  • Verifies the configuration inputs (makes sure the hostname resolves to the DNS, checks for the database and Redis servers, that the database credentials work, and that the proper database extensions are installed).
  • Verifies that the database does not have a current installation; if it does, the installation fails. To override this, either delete the database or use the -override switch (note you can not recover your data after using the override switch).

  • Initializes the database (this will destroy any data in the database).
  • Accepts the installation license key.

To create a new Installation

  1. If you are not already logged in to the Management node, log in as a user with administrator rights.
  2. At an elevated PowerShell prompt, run .\Centrify-PAS-NewInstallation.ps1.

    The script options can be provided on the command line. For example:

    .\Centrify-PAS-NewInstallation.ps1 -Hostname pas.corpnet.com -Certificate C:\corpnet.com.p12 -DBUser centrifyAccount -DBPassword secretCode -DBServer postgres.corpnet -RedisServer cache.corpnet -AdministratorName PASAdmin -AdministratorPassword EvenM0reS3cret -AdministratorEmail pasadmin@corpnet.com -CompanyName Corpnet -LicenseKey 234KL43

    Type Get-help .\Centrify-PAS-NewInstallation.ps1 -detail to get information on the command and parameters or see Centrify-PAS-NewInstallation.

    Note:   You can also pass configuration parameters via config.json file. If you use this method, you need to populate the config.json file with the required data prior to running the script, see Configuration file.

    If the command is successful, a zip file is created and available in the installations directory (\Installations\Config\<hostname>.zip) on the Management node.

  3. Copy the newly-created configuration directory to a safe and secure location.

    Note:    The configuration directory contains the generated certificates and keys for your installation, so it is important that you do not lose the contents.

Phase 3: Creating a Deployment package

Once an Installation is defined, use the Centrify-PAS-NewDeployment.ps1 to create a Deployment package (a .zip file) that you can distribute to cluster nodes (Web nodes, Background nodes, and TCP Relay nodes). The Centrify-PAS-NewDeployment.ps1 script updates the database schema and creates a Deployment in a new folder under the Installations\<hostname>\Deployments directory on the Management node, with the current date and the Deployment ID (as specified or as a GUID). Inside that directory is a single file called <Deployment ID>.zip that includes everything needed to create Web, Background, and TCP Relay nodes, including the configuration and certificate data.

Note:   An Installation must be created (see Phase 2: Creating a new Installation), prior to running the deployment package script.

To create a Deployment package

  1. If you are not already logged in to the Management node, log in as a user with administrator rights.
  2. Change to the target directory and at the PowerShell prompt, type Centrify-PAS-NewDeployment.ps1 [-Hostname][[-ID]]. See the following example:

    .\Centrify-PAS-NewDeployment.ps1 -Hostname pas.corpnet.com -ID NewDeploy1

    Type Get-help .\Centrify-PAS-NewDeployment.ps1 -detail to get information on the command and parameters or see Centrify-PAS-NewDeployment.

  3. Once complete the following file is available in the ...\installations\<hostname>\Deployments\<date-DeploymentID>\ directory:

    <deployment_id>.zip

Phase 4: Deploying Hyper-scalable PAS software to Web, Background, and TCP Relay nodes

After you complete the steps in previous sections, you copy the Deployment file (<deployment_id>.zip) from the Management node to each target node (Web, Background, TCP Relay) and then run Centrify-PAS-Deploy.ps1 to build each node. The illustration above depicts the deployment process. The deployment process is the same for each node with the exception of the command node type parameter.

When deploying (via Centrify-PAS-Deploy.ps1) a new Deployment, in addition to Web and Background nodes, you can also deploy two types of TCP Relay nodes: Logging node and the regular Relay node.

Note:   Centrify strongly recommends you install the Logging node first (if applicable), allowing the Web and Background nodes to see and log in to it.

To install each node:

You need to perform these procedures for each node (Web, Background, TCP Relay, and Logging node) in the Installation.

  1. Copy the deployment file, <deployment_id>.zip, from the Management node to the target node (the Windows 2016 servers designated as a Web, Background, TCP Relay, or Logging nodes).

    The <deployment_id>.zip file is created when you create the deployment package, (see To create a Deployment package) and is located in the \installations\<hostname>\Deployments\<date-DeploymentID>\ directory.

  2. On the target node, unzip the <deployment id>.zip file using the Expand-Archive commandlet or your preferred utility.
  3. On the target node, run the Centrify-PAS-Deploy.ps1 script with the appropriate parameter for the desired node type (see Centrify-PAS-Deploy for a list of parameters).

    Centrify strongly recommends you install the Logging node first (if applicable), to allow the Web and Background nodes to see and log in to it.

    For example, to create a Background node you enter:

    .\Centrify-PAS-Deploy.ps1 -BackgroundNode

    Type Get-help .\Centrify-PAS-Deploy.ps1 -detail to get information on the command and parameters or see Centrify-PAS-Deploy.

Phase 5: Activating the Deployment

There are two steps to activating a new Deployment. From the Management node:

  • Ensure that the load balancer can send traffic to the Web nodes.

    Note that Web nodes fail the health check until they are set to active.

  • Activate new nodes (Web and Background) by switching to the new Deployment ID.

When the Web node deployment is completed, add the new Web nodes to the target list of your load balancer. The health check URI is /health/check. Verify that the hostname resolves to the load balancer on your DNS, and then you are ready to activate the deployment so that it can service requests.

Note:   The Background nodes should have the same Deployment ID, but the load balancer only points at Web nodes.

When creating a new deployment, a new Deployment ID is created or assigned. Once the deployment is created, new nodes can be created, but those nodes won't respond to traffic until the load balancer points to the new Web nodes, and the new Deployment is set to Active. To activate inactive nodes, you run the .\Centrify-PAS-SetActiveDeployment.ps1 script from the Management node, specifying the desired Deployment ID.

At this point, any nodes in a previous Deployment ID are inactive and show as unhealthy or down in your load balancer, while the new nodes with matching Deployment IDs are active and show as healthy or up. Depending on the load balancer settings there may be a delay.

Note:   Hyper-scalable PAS does not support deactivating and then reactivating a deployment directly. Whenever a node is deactivated via Centrify-PAS-SetActiveDeployment, it must be rebooted before reactivating it.

To activate the deployment

  1. From the Management node, type the following to set the Deployment to active:

    Centrify-PAS-SetActiveDeployment.ps1 [-Hostname] <String> [-ID] <String>

    Type Get-help .\Centrify-PAS-SetActiveDeployment.ps1 -detail to get information on the command and parameters or see Centrify-PAS-SetActiveDeployment.

  2. Once the installation is complete, you can start using the Privileged Access Service.

Configuration file

During installation and deployment of Hyper-scalable PAS, you populate a configuration file with installation details using a JSON formatted file (config.json). The Centrify-PAS-NewInstallation.ps1 (see Phase 2: Creating a new Installation) requires this information during installation. To automate the process, you can add the information to config.json file yourself. Using this method, you enter the data directly into the config.json file prior to running the Centrify-PAS-NewInstallation.ps1 script. The file is stored in the installations\Config\hostname subdirectory. Make sure you also back up the configuration directory to a safe and secure location, as this has the generated certificates and keys for your installation.

The following is an example of using the config.json to pass parameters in the Centrify-PAS-NewInstallation.ps1 script.

You must provide the following information for the config.json file:

  • Redis: server hostname, server port (default is 6379)
  • Database: user name, password, server hostname, server port (default is 5432)
  • Hostname: this is the name of the installation and must match the hostname used on the certificate

Sample config.json file

Contents of config.json file: Description

{

"Redis": {

"ServerHost": "myredis",

"ServerPort": "6379",

"UseSSL": "False"

},

"Database": {

"UserName": "dbuser",

"Password": "secretPassword",

"ServerHost": "postgres.mycorp.net",

"ServerPort": "5432"

},

"Hostname": "pas.corpnet.com",

"Administrator": {

"UserName": "admin",

 

"Password": "tellNobody",

"Email": "admin@corpnet.com",

},

}

}

 

ServerHost: Enter hostname or an IP address.

 

 

 

 


UserName: Often defaults to postgres.

 

ServerHost: Name or IP Address of server.

 

 

Hostname: Must match the host certificate or be in its wildcard.


UserName: Enter an administrator login name. It should not match an Active Domain account user name.

Password: Password for the Centrify admin account.

Email: Enter the email account information for the admin account.