Configuring a PingFederate runtime

Configure an existing PingFederate environment as the token provider for PingAccess.

About this task

For information on configuring PingFederate as an OAuth authorization server, see OAuth configuration and Configuring authorization server settings in the PingFederate documentation.

Before configuring a secure connection to the PingFederate runtime, export the PingFederate certificate and import it into a trusted certificate group in PingAccess:

Steps

In PingFederate, export the active certificate for the runtime server.

For more information, see Manage SSL server certificates in the PingFederate documentation.
Import the certificate into PingAccess.
Create a trusted certificate group if one doesn’t already exist.
Add the certificate to the trusted certificate group.

Next steps

Select the tab for your environment configuration to continue. If your PingFederate instance is proxied by the PingAccess engines, use the proxied runtime procedure. Otherwise, choose one of the standard runtime procedures.

The steps that display on the Standard Runtime tab in the PingAccess administrative console depend on what PingAccess version you’re using:

If you’re using PingAccess 5.3 or later, some of the PingFederate configuration information is imported automatically from the PingFederate well-known endpoint. Use the standard runtime procedure.

If you upgrade from PingAccess 5.2 or earlier and have an existing token provider configuration, you must provide the PingFederate configuration information manually. Use the original standard runtime procedure.

If you perform an upgrade from PingAccess 5.2 or earlier and want to see the updated version of the Token Provider page in the administrative console, configure the token provider using the /pingfederate/runtime application programming interface (API) endpoint. For more information, see Administrative API Endpoints.

Configuring PingFederate as a token provider using the /pingfederate/runtime endpoint overwrites the existing PingFederate configuration.

Standard runtime
Original standard runtime
Proxied runtime

Configuring a standard PingFederate runtime

About this task

Configure a secure connection to the PingFederate runtime in PingAccess:

Steps

Click Settings, then go to System > Token Provider > PingFederate > Runtime.
Select Standard Token Provider.
In the Issuer field, enter the PingFederate issuer name.
Optional: In the Descriptions field, enter a description for the PingFederate instance.
In the Trusted Certificate Group list, select the certificate group that the PingFederate certificate is in.
To configure advanced settings, click Show Advanced.
1. If host name verification for secure connections isn’t required for either the runtime or the backchannel servers, select the Skip Hostname Verification check box.
2. To use a configured proxy for backchannel requests, select the Use Proxy check box.
  
  If the node is not configured with a proxy, requests are made directly to PingFederate.
  
  For more information about creating proxies, see Adding proxies.
3. Select Use Single-Logout to enable single logout (SLO) when the /pa/oidc/logout endpoint is accessed to clear the cookie containing the PingAccess token.
  
  If you select this option, PingAccess sends a sign off request to PingFederate, which completes a full SLO flow.
  
  To use this feature, SLO must be configured on the OpenID Provider (OP).
4. Enter the STS Token Exchange Endpoint to be used for token mediation if it’s different from the default value of <issuer>/pf/sts.wst.
Click Save.

Saving a new PingFederate runtime configuration overwrites any existing PingFederate runtime configuration.

Result

After you save the PingFederate runtime connection, PingAccess tests the connection to PingFederate. If the connection can’t be made, a warning displays in the admin console, and the PingFederate runtime won’t save.

Next steps

After you save this configuration and perform the steps in Configuring OAuth resource servers, a PingFederate access validator is available for selection when you define OAuth-type rules in the policy manager.

After you configure the token provider, click View Metadata to display the metadata provided by the token provider. To update the metadata, click Refresh Metadata.

Configuring a standard PingFederate runtime (original workflow)

About this task

If you’ve upgraded your PingAccess deployment from version 5.2 or earlier with an existing token provider configuration and haven’t configured a token provider using the /pingfederate/runtime API endpoint, use this workflow to configure a PingFederate runtime.

Steps

Click Settings, then go to System > Token Provider > PingFederate > Runtime.
Select Standard Token Provider.
In the Host field, enter the PingFederate runtime host name or the IP address for the PingFederate runtime.
In the Port field, enter the PingFederate runtime port number.
Optional: In the Base Path field, enter the base path for the PingFederate runtime.

The base path must start with a slash, such as /federation.
Select the Audit Level check box to log information about the transaction to the audit store.

PingAccess audit logs record a selected subset of transaction log information at runtime and are located in the /logs directory of your PingAccess installation.
In the Secure section, select Yes if PingFederate is expecting HTTPS connections.
In the Trusted Certificate Group list, select the certificate group that the PingFederate certificate is in.

This field is available only if you select Yes in step 7.
Click Show Advanced and configure the advanced settings:
1. Click Add Back Channel Server.
2. In the Back Channel Servers list, enter one or more <hostname:port> pairs.
3. If the backchannel uses HTTPS, enable the Back Channel Secure option.
  
  This option is available after you define at least one backchannel server.
4. If the backchannel uses an alternate base path, enter the path in the Back Channel Base Path field.
5. If host name verification for secure connections isn’t required for either the runtime or the backchannel servers, enable the Skip Hostname Verification option.
6. If host name verification is required, enter the host name that PingAccess should expect in the Expected Hostname field.
7. To use a configured proxy for backchannel requests, select the Use Proxy check box.
  
  If the node is not configured with a proxy, requests are made directly to PingFederate. For more information about creating proxies, see Adding proxies.
8. Select Use Single-Logout to enable single logout (SLO).
  
  To use this feature, SLO must be configured on the OpenID Connect (OIDC) provider.
Click Save.

Result

Next steps

After you configure the token provider, click View Metadata to display the metadata provided by the token provider. To update the metadata, click Refresh Metadata.

Configuring a proxied PingFederate runtime

About this task

Configure a secure connection to the proxied PingFederate runtime in PingAccess:

Steps

Click Settings, then go to System > Token Provider > PingFederate > Runtime.
Click Proxied Token Provider (PingFederate Runtime Application).
In the Primary Virtual Host field, enter the virtual host to use for the PingFederate application.

If you haven’t created the virtual host, click Create. For more information, see Creating new virtual hosts.

This virtual host is used by default for front-channel redirects to the PingFederate token provider when an application-specific OpenID Connect (OIDC) issuer isn’t defined.
Optional: In the Additional Virtual Hosts field, enter one or more virtual hosts that can be used for the PingFederate application.

If you haven’t created the virtual host, click Create. For more information, see Creating new virtual hosts.
In the Targets field, enter a hostname:port pair used to access the PingFederate runtime servers.

Click Add Target to add additional Targets fields.
In the Secure section, click Yes if the PingFederate runtime expects HTTPS connections.
In the Trusted Certificate Group list, select the certificate group the PingFederate certificate is in.

This field is available only if you select Yes in step 6.
In the Availability Profile list, select the availability profile that the PingFederate runtime should use.

To create a new availability profile, click Create.
To record requests to PingFederate to the audit store, select the Audit check box.

This check box is selected by default.

Optional: To configure advanced settings, click Show Advanced.

Option	Description
Context Root	Enter the first part of the URL path for the PingFederate application and its resources. The context root must begin with a slash. It can contain additional slashes, but cannot end with one. It must match the path defined by the base URL in PingFederate.
Case Sensitive	Select this check box to make the context root and resource path matching case sensitive.
Client Certificate Header Name	In this section, click Add Client Certificate Header Name and enter one or more header names to which PingAccess should map client certificates found in the request. The position of the header name in the list correlates to the index in the client certificate chain, with the first header mapped to the leaf certificate.
Policy	In this section, add one or more rules, rule sets, or rule set groups to run when making requests to the PingFederate runtime. Click Rules, Rule Sets, or Rule Set Groups, then drag one or more selections from the Available column to the Selected Policy column. Valid rule types are Groovy script, cross-origin request, and rewrite rules. Create new rules, rule sets, or rule set groups by clicking Create Rule, Create Rule Set, or Create Rule Set Group.
Load Balancing Strategy	In this list, select a load balancing strategy to use for requests to the PingFederate runtime. If you specify multiple target servers for a proxied PingFederate runtime but don’t apply a load balancing strategy, PingAccessuses the first target server in the list until it fails. Secondary target servers are only used if the first target server is not available. PingAccess uses the Failed Retry Timeout from the runtime’s availability profile settings to determine when to mark the first target server as available again.
Expected Certificate Hostname	Enter the host name expected in the certificate. If this field isn’t specified, certificates are verified using the target host names.
Skip Hostname Verification	Click to stop the backchannel servers from performing host name verification of the certificate.
Use Proxy	Click to make backchannel requests to PingFederate use the proxy configured on the PingAccess nodes.
Use Single-Logout	Click to enable single logout if it’s configured for the OP.

Option

Description

Context Root

Enter the first part of the URL path for the PingFederate application and its resources.

The context root must begin with a slash. It can contain additional slashes, but cannot end with one. It must match the path defined by the base URL in PingFederate.

Case Sensitive

Select this check box to make the context root and resource path matching case sensitive.

Client Certificate Header Name

In this section, click Add Client Certificate Header Name and enter one or more header names to which PingAccess should map client certificates found in the request.

The position of the header name in the list correlates to the index in the client certificate chain, with the first header mapped to the leaf certificate.

Policy

In this section, add one or more rules, rule sets, or rule set groups to run when making requests to the PingFederate runtime.

Click Rules, Rule Sets, or Rule Set Groups, then drag one or more selections from the Available column to the Selected Policy column.

Valid rule types are Groovy script, cross-origin request, and rewrite rules.
Create new rules, rule sets, or rule set groups by clicking Create Rule, Create Rule Set, or Create Rule Set Group.

Load Balancing Strategy

In this list, select a load balancing strategy to use for requests to the PingFederate runtime.

If you specify multiple target servers for a proxied PingFederate runtime but don’t apply a load balancing strategy, PingAccessuses the first target server in the list until it fails. Secondary target servers are only used if the first target server is not available.

PingAccess uses the Failed Retry Timeout from the runtime’s availability profile settings to determine when to mark the first target server as available again.

Expected Certificate Hostname

Enter the host name expected in the certificate.

If this field isn’t specified, certificates are verified using the target host names.

Skip Hostname Verification

Click to stop the backchannel servers from performing host name verification of the certificate.

Use Proxy

Click to make backchannel requests to PingFederate use the proxy configured on the PingAccess nodes.

Use Single-Logout

Click to enable single logout if it’s configured for the OP.

Click Save.

Saving a new PingFederate runtime configuration overwrites any existing PingFederate runtime configuration.

Result

Next steps

After you configure the token provider, click View Metadata to display the metadata provided by the token provider. To update the metadata, click Refresh Metadata.