Installing PingFederate 11.2 - PingFederate - 11.2

PingFederate Server

bundle
pingfederate-112
ft:publication_title
PingFederate Server
Product_Version_ce
PingFederate 11.2
category
Administrator
Administratorguide
Audience
Capability
ContentType
DeploymentMethod
Guide
Product
Productdocumentation
SingleSignonSSO
Software
SystemAdministrator
pf-112
pingfederate
ContentType_ce
Product documentation
Guide
Guide > Administrator Guide

You can install PingFederate on Windows and Linux operating systems.

Install PingFederate using the following methods:

  • Install PingFederate on a Windows system by running the installer for Windows or by extracting the distribution .zip archive. Using the installer for Windows is the preferred method.
  • Install PingFederate on a Linux system by extracting the distribution .zip archive.
Note:

This documentation refers to the installation directory path where the pingfederate directory is located as <pf_install>. For example, <pf_install>/pingfederate/bin.

Important:

To avoid future problems with automated upgrades, do not rename the installed pingfederate directory.

If you are installing multiple instances of PingFederate on the same machine, such as a console node and an engine node in a clustered environment, install each instance using a unique <pf_install> directory.

If you are upgrading an existing PingFederate environment, see Upgrading PingFederate.

Click the corresponding tabs for your preferred installation method.

Installing PingFederate on Linux systems

  • See System requirements for a list of qualified Linux operating systems.
  • Request a license key through the Ping Identity licensing website.
  • Ensure you are signed on to your system with sufficient privileges to install and run an application. You must install and run PingFederate under a local user account.
  • Verify that you have installed the Java Runtime Environment (JRE) and that you have set the required environment variables correctly. For more information, see Installing Java.

To install PingFederate on a Linux system using the distribution .zip archive:

  1. Download the latest version of the PingFederate Server distribution .zip archive from the Downloads website.
  2. Extract the archive into the target installation directory.
  3. Start PingFederate manually by running <pf_install>/pingfederate/bin/run.sh.
    Tip:

    To configure PingFederate to run as a service on Linux, install PingFederate on Linux manually.

    The startup process is complete when you see the following message.

    PingFederate running...

If your organization plans to manage keys and certificates using a hardware security module (HSM), see Supported hardware security modules.

Installing the PingFederate service on Linux manually

  • Request a license key through the Ping Identity licensing website.
  • Ensure you are signed on to your system with sufficient privileges to install and run an application.
  • Verify that you have installed the Java Runtime Environment (JRE) and that you have set the required environment variables correctly. For more information, see Installing Java in the PingFederate Server documentation.

If you have not installed PingFederate on Linux using the distribution .zip archive, you can install it manually. To install the PingFederate service on Linux manually:

  1. Download the distribution .zip archive from the Ping Identity website.
  2. Extract the file into an installation directory, <pf_install>.
  3. Create a new local user account for the PingFederate service, such as pingfederate.
    Note:

    The service account is referred to as <pf_user>.

  4. Change the ownership of the PingFederate installation directory <pf_install> and update the read-write permissions by running the following commands:
    chown -R <pf_user> <pf_install>
    chmod -R 775 <pf_install>
  5. If the operating system supports systemd, install the PingFederate unit file:
    1. Edit the <pf_install>/pingfederate/sbin/linux/pingfederate.service systemd unit file.

      Replace the following variables with information from your environment:

      ${PF_VERSION}
      The version of PingFederate.
      ${PF_USER}
      The local user account for the PingFederate service.
      ${PF_HOME}
      The <pf_install>/pingfederate directory.
      For example, if <pf_install> is /opt/identity.fed, replace ${PF_HOME} with /opt/identity.fed/pingfederate.
      ${PF_JAVA_HOME}
      The <JAVA_HOME> environment variable value (a directory).
    2. Copy the pingfederate.service file to the systemd unit files directory, for example, /etc/systemd/system.
      Note:

      Depending on the operating system, the exact location might vary. Consult your system administrators as needed. The rest of the step assumes /etc/systemd/system is the systemd unit files directory.

    3. Run the following command to update the read-write permissions of the pingfederate.service systemd unit file:
      chmod 664 /etc/systemd/system/pingfederate.service
    4. Run the following commands to load the new system configuration changes and start the PingFederate service:
      systemctl daemon-reload ;\
      systemctl start pingfederate
    5. Run the following commands to configure the PingFederate service to start automatically as the server boots:
      systemctl enable pingfederate ;\
      systemctl daemon-reload ;\
      systemctl restart pingfederate

    After setting up the PingFederate systemd unit file, you can run the following systemctl command to manage the PingFederate service:

    systemctl start pingfederate
    systemctl stop pingfederate
    systemctl restart pingfederate
    systemctl status pingfederate
  6. If the operating system supports SysV initialization, follow these steps to install the PingFederate script.
    1. Edit the <pf_install>/pingfederate/sbin/linux/pingfederate script.

      Replace the following statements with information from your environment:

      PF_HOME=$PF_HOME
      Replace $PF_HOME with the <pf_install>/pingfederate directory.
      For example, if <pf_install> is /opt/identity.fed, replace $PF_HOME with /opt/identity.fed/pingfederate.
      USER="pingfederate"
      If the PingFederate service account is not pingfederate, replace <pingfederate> with the local user account for the PingFederate service.
      For example, if <pf_user> is pingfed, replace <pingfederate> with pingfed.
      Example (truncated)
      If <pf_install> and <pf_user> are /opt/identity.fed and pingfederate respectively, the required modifications are:
      ...
      PF_HOME=/opt/identity.fed/pingfederate
      DIR="$PF_HOME/sbin"
      USER="pingfederate"
      ...
    2. Copy the pingfederate script to the SysV initialization directory, for example, /etc/rc.d/init.d.

      The exact location might vary, depending on the operating system. Consult your system administrators, as needed. The rest of the step assumes /etc/rc.d/init.d is the SysV initialization directory.

    3. Run the following command to update the read-write permissions of the pingfederate SysV initialization script:
      chmod 755 /etc/rc.d/init.d/pingfederate
    4. Configure the operating system to start the PingFederate service at various runlevels.

      On an RHEL server, you can use the Service Configuration utility to do so.

      Alternatively, the initialization directories associated with various runlevels can accept manual symbolic links of the pingfederate script by running the ln -s <source> <target> command.

      You can create the following symbolic links on an RHEL server where runlevels 2 and 4 are not used:

      ln -s /etc/rc.d/init.d/pingfederate /etc/rc3.d/S84pingfederate
      ln -s /etc/rc.d/init.d/pingfederate /etc/rc5.d/S84pingfederate
      ln -s /etc/rc.d/init.d/pingfederate /etc/rc0.d/K15pingfederate
      ln -s /etc/rc.d/init.d/pingfederate /etc/rc1.d/K15pingfederate
      ln -s /etc/rc.d/init.d/pingfederate /etc/rc6.d/K15pingfederate
      Note:

      Some operating systems might require a restart of the system to activate the new scripts. Consult your system administrators as needed.

After setting up the PingFederate SysV initialization script, you can use the Service Configuration utility or run the following service commands to manage the PingFederate service:

service pingfederate start
service pingfederate stop
service pingfederate restart
service pingfederate status

Installing PingFederate on Windows

  • Request a license key through the Ping Identity licensing page.
  • Ensure your are signed on to your system with sufficient privileges to install and run an application.
  • Verify that you have installed the Java Runtime Environment (JRE) and that you have set the required environment variables correctly. For more information, see Installing Java.

You can install PingFederate on a Windows system using the installer for Windows or the distribution .zip archive. Using the installer for Windows is the preferred method.

Tip:

To configure PingFederate to run as a service on Windows, install PingFederate on Windows manually. For more information, see Installing the PingFederate service on Windows manually.

To install PingFederate:

  1. Install PingFederate using the installer for Windows or the distribution .zip archive:
    • To install using the PingFederate installer for Windows:

      1. Download the PingFederate installer for Windows from the Ping Identity website.
      2. Double-click the .msi file to open the PingFederate Setup Wizard, and follow the instructions to complete the installation.

      PingFederate is configured to run as a service and starts automatically at the end of the installation process.

      Note:

      The PingFederate installer for Windows installs only one instance of PingFederate on a Windows server. If you need additional PingFederate instances on the same Windows server, install them using the distribution .zip archive.

      You must manually configure various port settings in the <pf_install>/pingfederate/bin/run.properties file for each instance to avoid port conflicts.

    • To install PingFederate using the distribution .zip archive:

      1. Download the distribution .zip archive from the Ping Identity website. The distribution .zip archive is identical for both Windows and Linux.
      2. Extract the file into an installation directory.
  2. If you have installed PingFederate by extracting the distribution .zip archive, start PingFederate manually by running <pf_install>/pingfederate/bin/run.bat.

    Wait for the script to finish. The startup process completes when you see the following message.

    PingFederate running...
    CAUTION:

    When running PingFederate for Windows, switching the Java version from 8 to 11 (or the reverse) prevents the service from running, and you won't be able to start PingFederate. The problem occurs because garbage collection logging configuration arguments that are used by Java 8 are incompatible with those used by Java 11.

    To change Java versions:

    1. Run <pf_install>\pingfederate\sbin\win-x86-64\uninstall-service.bat to de-register the PingFederate service.
    2. Install the new Java version and update the JAVA_HOME and PATH environment variables.
    3. Run <pf_install>\pingfederate\sbin\win-x86-64\install-service.bat to register the PingFederate service.

If your organization plans to manage keys and certificates using a hardware security module (HSM), see Supported hardware security modules.

Installing the PingFederate service on Windows manually

  • Request a license key through the Ping Identity licensing website.
  • Ensure you are signed on to your system with sufficient privileges to install and run an application.
  • Verify that you have installed the Java Runtime Environment (JRE) and that you have set the required environment variables correctly. See Installing Java.
Note:

If you have installed PingFederate using the installer for Windows, skip these steps because PingFederate has already been configured to run as a service and to start automatically at the end of the installation process.

To install the PingFederate service manually:

  1. Download the distribution .zip archive from the Ping Identity website.

    The distribution .zip archive is identical for both Windows and Linux.

  2. Extract the archive into an installation directory, <pf_install>.
  3. Start PowerShell or Command Prompt as an administrator.
  4. Run the <pf_install>\pingfederate\sbin\win-x86-64\install-service.bat file.
  5. Go to Control Panel > Administrative Tools > Services to open the management console.
  6. Right-click the PingFederate service and select Start.

The PingFederate service starts automatically on reboot.