Prepare to install

Before you install, make sure your installation meets the requirements in the release notes.

Create a PingGateway service account

To limit the impact of a security breach, install and run PingGateway from a dedicated service account. This is optional when evaluating PingGateway, but essential in production installations.

A hacker is constrained by the rights granted to the user account where PingGateway runs; therefore, never run PingGateway as root user.

In a terminal window, use a command similar to the following to create a service account:

Linux
Windows

$ sudo /usr/sbin/useradd \
--create-home \
--comment "Account for running PingGateway" \
--shell /bin/bash PingGateway

> net user username password /add /comment:"Account for running PingGateway"

Apply the principle of least privilege to the account, for example:
- Read/write permissions on the installation directory, /path/to/identity-gateway-2024.9.0.
- Execute permissions on the scripts in the installation bin directory, /path/to/PingGateway-2024.9.0/bin.

Prepare the network

Configure the network to include hosts for PingGateway, AM, and the sample application. Learn more about host files from the Wikipedia entry, Hosts (file).

Add the following entry to your host file:

Linux
Windows

/etc/hosts

%SystemRoot%\system32\drivers\etc\hosts

127.0.0.1  localhost ig.example.com app.example.com am.example.com

Set up PingOne Advanced Identity Cloud

This documentation contains procedures for setting up items in PingOne Advanced Identity Cloud that you can use with PingGateway. For more information about setting up PingOne Advanced Identity Cloud, refer to the PingOne Advanced Identity Cloud documentation.

Authenticate a PingGateway agent to PingOne Advanced Identity Cloud

PingGateway agents are automatically authenticated to PingOne Advanced Identity Cloud by a non-configurable authentication module. Authentication chains and modules are deprecated in PingOne Advanced Identity Cloud and replaced by journeys.

You can now authenticate PingGateway agents to PingOne Advanced Identity Cloud with a journey. The procedure is currently optional, but will be required when authentication chains and modules are removed in a future release of PingOne Advanced Identity Cloud.

For more information, refer to PingOne Advanced Identity Cloud’s Journeys.

This section describes how to create a journey to authenticate an PingGateway agent to PingOne Advanced Identity Cloud. The journey has the following requirements:

It must be called Agent
Its nodes must pass the agent credentials to the Agent Data Store Decision node.

When you define a journey in PingOne Advanced Identity Cloud, that same journey is used for all instances of PingGateway, Java agent, and Web agent. Consider this point if you change the journey configuration.

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
Click Journeys > New Journey.
Add a journey with the following information and click Create journey:
- Name: Agent
- Identity Object: The user or device to authenticate.
- (Optional) Description: Authenticate a PingGateway agent to PingOne Advanced Identity Cloud
The journey designer is displayed, with the Start entry point connected to the Failure exit point, and a Success node.
Using the Filter nodes bar, find and then drag the following nodes from the Components panel into the designer area:
- Zero Page Login Collector node to check whether the agent credentials are provided in the incoming authentication request, and use their values in the following nodes.
  
  This node is required for compatibility with Java agent and Web agent.
- Page node to collect the agent credentials if they are not provided in the incoming authentication request, and use their values in the following nodes.
- Agent Data Store Decision node to verify the agent credentials match the registered PingGateway agent profile.
Many nodes can be configured in the panel on the right side of the page. Unless otherwise stated, do not configure the nodes, and use only the default values.
Drag the following nodes from the Components panel into the Page node:
- Platform Username node to prompt the user to enter their username.
- Platform Password node to prompt the user to enter their password.
Connect the nodes as follows and save the journey:

Register a PingGateway agent in PingOne Advanced Identity Cloud

This procedure registers an agent profile for PingGateway.

Click verified_user Gateways & Agents > New Gateway/Agent > Identity Gateway > Next and use the hints in the following table to create the agent profile:

Field Description Example

Field	Description	Example
ID	Set the unique agent profile name PingGateway uses to connect.	`ig_agent`
Password	Store the password PingGateway uses to connect in the agent profile. Record the password to use when configuring PingGateway.	A strong password. The examples in the documentation use `password` and its base64-encoding `cGFzc3dvcmQ=`.
Use Secret Store for password	Store the password in a secret and reference the secret by its label. Follow the steps in Use the secret store for the password after you create the agent profile.	Click to enable
Secret Label Identifier	This field appears when you select Use Secret Store for password. This value represents the `identifier` part of the secret label for the agent. PingOne Advanced Identity Cloud uses the identifier to generate a secret label in the following format: `am.application.agents.identifier.secret`. Learn more in Secret labels. After setting this, add an ESV secret for the password and map the ESV to the secret label.	`ig`

Set the unique agent profile name PingGateway uses to connect.

ig_agent

Password

Store the password PingGateway uses to connect in the agent profile.

Record the password to use when configuring PingGateway.

A strong password.

The examples in the documentation use password and its base64-encoding cGFzc3dvcmQ=.

Use Secret Store for password

Store the password in a secret and reference the secret by its label.

Follow the steps in Use the secret store for the password after you create the agent profile.

Click to enable

Secret Label Identifier

This field appears when you select Use Secret Store for password.

This value represents the identifier part of the secret label for the agent. PingOne Advanced Identity Cloud uses the identifier to generate a secret label in the following format: am.application.agents.identifier.secret. Learn more in Secret labels.

After setting this, add an ESV secret for the password and map the ESV to the secret label.

ig

Use secure passwords in a production environment. Consider using a password manager to generate secure passwords.

Click Save Profile > Done to display the new agent profile.
(Optional) Add the list of Redirect URLs used in PingGateway routes and click Save to update the profile.

Use the secret store for the password

When you select Use Secret Store for password and set a secret label for the agent profile, PingOne Advanced Identity Cloud creates the secret label but the secret isn’t yet defined or mapped to the label:

Define an ESV secret, such as esv-ig_agent, holding the password for PingGateway to connect.

The examples in the documentation use password.

Learn how in creating ESV secrets. In production deployments, restrict access to the password from configuration placeholder and script contexts.
Map the ESV to the label created when you set the Secret Label Identifier:
1. Click open_in_new Native Consoles > Access Management > Secret Stores > ESV > Mappings > Add mappings.
2. In the Add Mapping modal, select the label, such as am.application.agents.ig.secret, in the Secret Label list.
3. In the aliases field, enter the ESV secret, such as esv-ig_agent, and click Add.
4. Click Create to add the mapping:
Learn more in Map ESV secrets to secret labels.

Note the following points:

If you update or delete the Secret Label Identifier, AM updates or deletes the corresponding mapping for the previous identifier unless another agent shares the mapping.
When you rotate a secret, update the corresponding mapping.

Optional settings

In the AM admin UI, consider the following additional optional settings for the agent profile under Applications > Agents > Identity Gateway > agent ID:

To direct login to a custom URL instead of the default AM login page, configure Login URL Template for CDSSO.
To apply a different introspection scope, click Token Introspection and select a scope from the list.
Click Save to update the profile.

Set up a demo user in PingOne Advanced Identity Cloud

This procedure sets up a demo user in the alpha realm.

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
Go to group Identities > Manage > settings_system_daydream Alpha realm - Users, and add a user with the following values:
- Username: demo
- First name: demo
- Last name: user
- Email Address: demo@example.com
- Password: Ch4ng3!t

Recommendations

Use PingGateway with PingOne Advanced Identity Cloud as you would with any other service.

During updates, individual PingOne Advanced Identity Cloud tenant servers go offline temporarily. PingGateway can receive HTTP 502 Bad Gateway responses for some requests during the update.

In your ClientHandler and ReverseProxyHandler configurations, configure PingGateway to retry operations when this occurs:
```
"retries": {
    "enabled": true,
    "condition": "${response.status.code == 502}"
}
```
Update PingGateway to use the latest version you can to benefit from fixes and improvements.

Set up AM

This documentation contains procedures for setting up items in AM that you can use with PingGateway. For more information about setting up AM, refer to the Access Management documentation.

Authenticate a PingGateway agent to AM

From AM 7.3: When AM 7.3 is installed with a default configuration, as described in Evaluation, PingGateway is automatically authenticated to AM by an authentication tree. Otherwise, PingGateway is authenticated to AM by an AM authentication module.

Authentication chains and modules were deprecated in AM 7. When they are removed in a future release of AM, it will be necessary to configure an appropriate authentication tree when you are not using the default configuration.

For more information, refer to AM’s Authentication nodes and trees.

This section describes how to create an authentication tree to authenticate a PingGateway agent to AM. The tree has the following requirements:

It must be called Agent
Its nodes must pass the agent credentials to the Agent Data Store Decision node.

When you define a tree in AM, that same tree is used for all instances of PingGateway, Java agent, and Web agent. Consider this point if you change the tree configuration.

On the Realms page of the AM admin UI, choose the realm in which to create the authentication tree.
On the Realm Overview page, click Authentication > Trees > Create tree.

Create a tree named Agent.

The authentication tree designer is displayed, with the Start entry point connected to the Failure exit point and a Success node.

The authentication tree designer provides the following features on the toolbar:

Button Usage

Button	Usage
	Lay out and align nodes according to the order they are connected.
	Toggle the designer window between normal and full-screen layout.
	Remove the selected node. Note that the `Start` entry point cannot be deleted.

Lay out and align nodes according to the order they are connected.

Toggle the designer window between normal and full-screen layout.

Remove the selected node. Note that the Start entry point cannot be deleted.

Using the Filter bar, find and then drag the following nodes from the Components panel into the designer area:
- Zero Page Login Collector node to check whether the agent credentials are provided in the incoming authentication request, and use their values in the following nodes.
  
  This node is required for compatibility with Java agent and Web agent.
- Page node to collect the agent credentials if they are not provided in the incoming authentication request, and use their values in the following nodes.
- Agent Data Store Decision node to verify the agent credentials match the registered PingGateway agent profile.
Many nodes can be configured in the panel on the right side of the page. Unless otherwise stated, do not configure the nodes and use only the default values.
Drag the following nodes from the Components panel into the Page node:
- Username Collector node to prompt the user to enter their username.
- Password Collector node to prompt the user to enter their password.
Connect the nodes as follows and save the tree:

Register a PingGateway agent in AM

In AM 7 and later versions, follow these steps to register an agent that acts on behalf of PingGateway.

In the AM admin UI, select the top-level realm, and then select Applications > Agents > Identity Gateway.
Add an agent with the following configuration, leaving other options blank or with the default value:
- For SSO
- For CDSSO
Agent ID : ig_agent

Password : password
Agent ID : ig_agent

Password : password

Redirect URL for CDSSO : https://ig.ext.com:8443/home/cdsso/redirect

Login URL Template for CDSSO: Configure this property to direct login to a custom URL instead of the default AM login page.
(Optional - From AM 7.5) Use AM’s secret service to manage the agent profile password. If AM finds a matching secret in a secret store, it uses that secret instead of the agent password configured in Step 2.
1. In the agent profile page, set a label for the agent password in Secret Label Identifier.
  
  AM uses the identifier to generate a secret label for the agent.
  
  The secret label has the format am.application.agents.identifier.secret, where identifier is the Secret Label Identifier.
  
  The Secret Label Identifier can contain only characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.
2. Select Secret Stores and configure a secret store.
3. Map the label to the secret. Learn more from AM’s mapping.
Note the following points for using AM’s secret service:
- Set a Secret Label Identifier that clearly identifies the agent.
- If you update or delete the Secret Label Identifier, AM updates or deletes the corresponding mapping for the previous identifier provided no other agent shares the mapping.
- When you rotate a secret, update the corresponding mapping.

Set up a demo user in AM

AM is provided with a demo user in the top-level realm, with the following credentials:

ID/username: demo
Last name: user
Password: Ch4ng31t
Email address: demo@example.com
Employee number: 123

For information about how to manage identities in AM, refer to AM’s Identity stores.

In routes that use AmService, PingGateway retrieves AM’s SSO cookie name from the ssoTokenHeader property or from AM’s /serverinfo/* endpoint.

In other circumstances where you need to find the SSO cookie name, access http://am-base-url/serverinfo/*. For example, access the AM endpoint with curl:

$ curl http://am.example.com:8088/openam/json/serverinfo/*

PingGateway 2024.9