PingAuthorize

Common manage-profile workflows

You can use the manage-profile tool to complete a variety of workflows in PingAuthorize.

This section describes how to use the manage-profile tool to accomplish typical server-management tasks, like the following examples:

The following sections describe these tasks in more detail. For more information about the manage-profile tool, run manage-profile --help. For more information about each individual subcommand and its options, run manage-profile <subcommand> --help.

Creating a server profile

You can create a server profile from a configured server in PingAuthorize Server.

About this task

To create a server profile from a configured server, use the generate-profile subcommand.

Steps

  1. Create a profile directory.

    Example:

    $ mkdir -p /opt/server-profiles/pingauthorize

  2. Run generate-profile.

    Example:

    $ bin/manage-profile generate-profile --profileRoot /opt/server-profiles/pingauthorize

  3. Customize the resulting profile to suit your needs and to remove deployment environment-specific values.

    Choose from:

    • Specify a consistent location for the license key file:

      1. Copy the license key file to the server profile’s misc-files directory.

        $ cp  {pingauthorize}.lic /opt/server-profiles/pingauthorize/misc-files/

      2. Open the setup-arguments.txt file in a standard text editor.

      3. Locate the --licenseKeyFile argument.

      4. Change the value of --licenseKeyFile to the following value.

        Use PING_PROFILE_ROOT only with files that are not needed after initial setup, such as password files in setup-arguments.txt. Do not use the PING_PROFILE_ROOT variable for files needed while the server is running. The manage-profile tool creates a temporary copy of the server profile that is deleted after the tool completes, so files are not accessible under PING_PROFILE_ROOT when the server is running. For files you need while the server is running, such as keystore and truststore files, copy the files into the server root using the profile’s server-root/pre-setup directory, and then refer to the files using with the PING_SERVER_ROOT variable.

        		 
        ${PING_PROFILE_ROOT}/misc-files/{pingauthorize}.lic

      5. Save your changes.

    • Remove deployment environment-specific values and replace them with variables. For example, to refer to a different PingFederate server in your development environments versus your test environments, perform the following steps:

      1. Open the /opt/server-profiles/pingauthorize/dsconfig/00-config.dsconfig file in a standard text editor.

      2. Locate the value specified for base-url for the external server that identifies your PingFederate server.

      3. Replace the value with a variable, like ${PF_BASE_URL}.

      4. Save your changes.

      5. Create or update a server profile variables file for your development environment.

      6. Add a row like the following example to the variables file.

        PF_BASE_URL=https://sso.dev.example.com:9031

      7. Save your changes.

      8. Continue replacing deployment environment-specific values with variables until the server profile contains no more deployment environment-specific values.

        At this point, you can check the server profile in to a version-control system, like Git, share with your team, and integrate into your deployment automation.

Installing a new environment

You can use manage-profile setup to set up a new server instance and deployment environment in PingAuthorize Server.

Before you begin

The steps in this section make the following assumptions:

  • A server profile has already been created at the path ~/git/server-profiles/pingauthorize.

  • Your development environment’s variables file is saved at the path ~/pingauthorize-variables-dev.env.

About this task

After you create and customize a server profile, use the manage-profile setup subcommand to set up new server instances and additional deployment environments.

The setup subcommand completes the following tasks:

  • Copies the server root files

  • Runs the setup tool

  • Runs the dsconfig batch files

  • Installs the server SDK extensions

  • Sets the server’s cluster name to a unique value

    Cluster-wide configuration is automatically mirrored across all servers in the topology with the same cluster name. In a DevOps deployment with immutable servers, configuration mirroring introduces risk. Therefore, in most cases, cluster names should be unique for each server to avoid configuration mirroring.

Steps

  1. Extract the contents of the compressed archive to a directory of your choice.

    Example:

    $ mkdir /opt/pingauthorize
$ cd /opt/pingauthorize
$ unzip  {pingauthorize}-<version>.zip

  2. Change directories.

    Example:

    $ cd  {pingauthorize}

  3. Run setup.

    Example:

    $ bin/manage-profile setup \
  --profile ~/git/server-profiles/pingauthorize \
  --profileVariablesFile ~/pingauthorize-variables-dev.env

Scaling up your environment

You can scale up the environment in your PingAuthorize Server instance.

About this task

The automation for this task is identical to the previous task of installing a new server in a new environment. Because each instance of PingAuthorize Server requires a unique instance name and host name, each instance must also be set up from a unique server profile variables file.

Rolling out an update

When you roll out a PingAuthorize Server update, run manage-profile replace-profile to use a server profile that you have set up.

Before you begin

The steps in this section make the following assumptions:

  • A server profile has been created at the path ~/git/server-profiles/pingauthorize.

  • The server’s server profile variables file is saved at the path /opt/pingauthorize/pingauthorize-variables.env.

  • The existing server with the earlier configuration is installed at /opt/pingauthorize/PingAuthorize.

About this task

Run the replace-profile subcommand on a server that was originally set up with a server profile to replace its configuration with a new profile. The replace-profile subcommand applies a specified server profile to an existing server while also preserving its configuration.

While manage-profile replace-profile is running, the existing server is stopped and moved to a temporary directory that the --tempServerDirectory argument specifies. A fresh, new server is subsequently installed and set up with the new profile. If the final server was running before the command was started, it is left running. If the final server was stopped, it remains stopped.

If files have been added or modified in the server root since you ran the most recent manage-profile setup or manage-profile replace-profile subcommand, they are included in the final server with the replaced profile. Otherwise, files added specifically from the server-root directory of the previous server profile are absent from the final server with the replaced profile.

If errors occur while running the subcommand, such as the new profile having an invalid setup-arguments.txt file, the existing server returns to its original state from before you ran manage-profile replace-profile.

Steps

  1. Extract the distribution package for the same or a new version of PingAuthorize Server to a location outside the existing server’s installation.

    Example:

    $ mkdir ~/stage
$ cd ~/stage
$ unzip  {pingauthorize}-<version>.zip

  2. Change directories.

    You must run the replace-profile subcommand from the location of the distribution package, not from the existing server.

    Example:

    $ cd  {pingauthorize}

  3. Run replace-profile.

    Example:

    $ bin/manage-profile replace-profile \
  --serverRoot /opt/pingauthorize/{pingauthorize}  \
  --profile ~/git/server-profiles/pingauthorize \
  --profileVariablesFile ~/pingauthorize-variables-dev.env